@aaronsb/jira-cloud-mcp 0.1.0

package/build/utils/formatters/issue-formatter.js

@@ -0,0 +1,84 @@
+import { BaseFormatter } from './base-formatter.js';
+export class IssueFormatter {
+    /**
+     * Format an issue response with the standard structure and optional expansions
+     * @param issue The issue data
+     * @param options Expansion options
+     * @param transitions Optional transitions data (if requested)
+     * @returns A formatted issue response
+     */
+    static formatIssue(issue, options = {}, transitions) {
+        // Create metadata with available expansions
+        const metadata = this.createIssueMetadata(issue, options, transitions);
+        // Create summary with status and suggested actions
+        const summary = this.createIssueSummary(issue, transitions);
+        return BaseFormatter.formatResponse(issue, metadata, summary);
+    }
+    /**
+     * Create metadata for an issue response
+     */
+    static createIssueMetadata(issue, options, transitions) {
+        // Determine which expansions are available but not included
+        const availableExpansions = [];
+        if (!options.comments && issue.comments === undefined) {
+            availableExpansions.push('comments');
+        }
+        if (!options.transitions && transitions === undefined) {
+            availableExpansions.push('transitions');
+        }
+        if (!options.attachments && issue.attachments === undefined) {
+            availableExpansions.push('attachments');
+        }
+        if (!options.related_issues) {
+            availableExpansions.push('related_issues');
+        }
+        if (!options.history) {
+            availableExpansions.push('history');
+        }
+        // Create related entities map
+        const related = {};
+        if (issue.parent) {
+            related.parent = issue.parent;
+        }
+        // Extract related issues from issue links
+        const relatedIssues = issue.issueLinks
+            .map(link => link.outward || link.inward)
+            .filter((key) => key !== null);
+        if (relatedIssues.length > 0) {
+            related.linked_issues = relatedIssues;
+        }
+        return BaseFormatter.createMetadata({
+            expansions: availableExpansions,
+            related
+        });
+    }
+    /**
+     * Create a summary for an issue response
+     */
+    static createIssueSummary(issue, transitions) {
+        const suggestedActions = [];
+        // Add suggested actions based on available transitions
+        if (transitions && transitions.length > 0) {
+            // Common transitions to suggest
+            const commonTransitions = ['Done', 'In Progress', 'To Do', 'Closed', 'Resolved'];
+            for (const transitionName of commonTransitions) {
+                const transition = transitions.find(t => t.name === transitionName);
+                if (transition) {
+                    suggestedActions.push({
+                        text: `Move to ${transitionName}`,
+                        action_id: transition.id
+                    });
+                }
+            }
+        }
+        // Add assignment suggestion if not assigned
+        if (!issue.assignee) {
+            suggestedActions.push({
+                text: 'Assign to team member'
+            });
+        }
+        return BaseFormatter.createSummary({
+            suggested_actions: suggestedActions
+        });
+    }
+}

package/build/utils/formatters/project-formatter.js

@@ -0,0 +1,55 @@
+import { BaseFormatter } from './base-formatter.js';
+export class ProjectFormatter {
+    /**
+     * Format a project response with the standard structure and optional expansions
+     * @param project The project data
+     * @param options Expansion options
+     * @returns A formatted project response
+     */
+    static formatProject(project, options = {}) {
+        // Create metadata with available expansions
+        const metadata = this.createProjectMetadata(project, options);
+        // Create summary with status counts
+        const summary = this.createProjectSummary(project);
+        return BaseFormatter.formatResponse(project, metadata, summary);
+    }
+    /**
+     * Create metadata for a project response
+     */
+    static createProjectMetadata(project, options) {
+        // Determine which expansions are available but not included
+        const availableExpansions = [];
+        if (!options.boards) {
+            availableExpansions.push('boards');
+        }
+        if (!options.components) {
+            availableExpansions.push('components');
+        }
+        if (!options.versions) {
+            availableExpansions.push('versions');
+        }
+        if (!options.recent_issues) {
+            availableExpansions.push('recent_issues');
+        }
+        return BaseFormatter.createMetadata({
+            expansions: availableExpansions
+        });
+    }
+    /**
+     * Create a summary for a project response
+     */
+    static createProjectSummary(project) {
+        const suggestedActions = [
+            {
+                text: `View all issues in ${project.key}`
+            },
+            {
+                text: `Create issue in ${project.key}`
+            }
+        ];
+        return BaseFormatter.createSummary({
+            status_counts: project.status_counts,
+            suggested_actions: suggestedActions
+        });
+    }
+}

package/build/utils/formatters/search-formatter.js

@@ -0,0 +1,62 @@
+import { BaseFormatter } from './base-formatter.js';
+export class SearchFormatter {
+    /**
+     * Format a search response with the standard structure and optional expansions
+     * @param searchResult The search result data
+     * @param options Expansion options
+     * @returns A formatted search response
+     */
+    static formatSearchResult(searchResult, options = {}) {
+        // Create metadata with available expansions and pagination
+        const metadata = this.createSearchMetadata(searchResult, options);
+        // Create summary with status counts
+        const summary = this.createSearchSummary(searchResult);
+        return BaseFormatter.formatResponse(searchResult, metadata, summary);
+    }
+    /**
+     * Create metadata for a search response
+     */
+    static createSearchMetadata(searchResult, options) {
+        // Determine which expansions are available but not included
+        const availableExpansions = [];
+        if (!options.issue_details) {
+            availableExpansions.push('issue_details');
+        }
+        if (!options.transitions) {
+            availableExpansions.push('transitions');
+        }
+        if (!options.comments_preview) {
+            availableExpansions.push('comments_preview');
+        }
+        return BaseFormatter.createMetadata({
+            expansions: availableExpansions,
+            pagination: {
+                startAt: searchResult.pagination.startAt,
+                maxResults: searchResult.pagination.maxResults,
+                total: searchResult.pagination.total
+            }
+        });
+    }
+    /**
+     * Create a summary for a search response
+     */
+    static createSearchSummary(searchResult) {
+        // Count issues by status
+        const statusCounts = {};
+        for (const issue of searchResult.issues) {
+            const status = issue.status;
+            statusCounts[status] = (statusCounts[status] || 0) + 1;
+        }
+        const suggestedActions = [];
+        // Add pagination actions if there are more results
+        if (searchResult.pagination.hasMore) {
+            suggestedActions.push({
+                text: 'Load more results'
+            });
+        }
+        return BaseFormatter.createSummary({
+            status_counts: statusCounts,
+            suggested_actions: suggestedActions
+        });
+    }
+}

package/build/utils/formatters/sprint-formatter.js

@@ -0,0 +1,111 @@
+import { BaseFormatter } from './base-formatter.js';
+export class SprintFormatter {
+    /**
+     * Format a sprint response with the standard structure and optional expansions
+     * @param sprint The sprint data
+     * @param options Expansion options
+     * @returns A formatted sprint response
+     */
+    static formatSprint(sprint, options = {}) {
+        // Create metadata with available expansions
+        const metadata = this.createSprintMetadata(sprint, options);
+        // Create summary
+        const summary = this.createSprintSummary(sprint);
+        return BaseFormatter.formatResponse(sprint, metadata, summary);
+    }
+    /**
+     * Format a list of sprints
+     * @param sprints Array of sprint data
+     * @param pagination Pagination information
+     * @returns A formatted response with sprints array
+     */
+    static formatSprintList(sprints, pagination) {
+        // Create metadata
+        const metadata = {};
+        if (pagination) {
+            metadata.pagination = {
+                startAt: pagination.startAt,
+                maxResults: pagination.maxResults,
+                total: pagination.total,
+                hasMore: pagination.startAt + pagination.maxResults < pagination.total,
+            };
+        }
+        // Create summary with status counts
+        const statusCounts = {
+            future: 0,
+            active: 0,
+            closed: 0,
+        };
+        sprints.forEach(sprint => {
+            if (sprint.state && statusCounts[sprint.state] !== undefined) {
+                statusCounts[sprint.state]++;
+            }
+        });
+        const summary = {
+            status_counts: statusCounts,
+            suggested_actions: [
+                { text: 'Create new sprint', action_id: 'create_sprint' },
+            ],
+        };
+        return BaseFormatter.formatResponse(sprints, metadata, summary);
+    }
+    /**
+     * Create metadata for a sprint response
+     */
+    static createSprintMetadata(sprint, options) {
+        // Determine which expansions are available but not included
+        const availableExpansions = [];
+        if (!options.issues && !sprint.issues) {
+            availableExpansions.push('issues');
+        }
+        if (!options.report && !sprint.report) {
+            availableExpansions.push('report');
+        }
+        // Create related entities map
+        const related = {
+            board: sprint.boardId.toString(),
+        };
+        return BaseFormatter.createMetadata({
+            expansions: availableExpansions,
+            related
+        });
+    }
+    /**
+     * Create a summary for a sprint response
+     */
+    static createSprintSummary(sprint) {
+        const suggestedActions = [];
+        // Add suggested actions based on sprint state
+        switch (sprint.state) {
+            case 'future':
+                suggestedActions.push({ text: 'Start Sprint', action_id: 'start_sprint' });
+                suggestedActions.push({ text: 'Add Issues to Sprint', action_id: 'add_issues' });
+                suggestedActions.push({ text: 'Edit Sprint', action_id: 'update_sprint' });
+                break;
+            case 'active':
+                suggestedActions.push({ text: 'Complete Sprint', action_id: 'complete_sprint' });
+                suggestedActions.push({ text: 'Add Issues to Sprint', action_id: 'add_issues' });
+                suggestedActions.push({ text: 'Remove Issues from Sprint', action_id: 'remove_issues' });
+                suggestedActions.push({ text: 'Edit Sprint', action_id: 'update_sprint' });
+                break;
+            case 'closed':
+                suggestedActions.push({ text: 'View Sprint Report', action_id: 'view_report' });
+                suggestedActions.push({ text: 'Create New Sprint', action_id: 'create_sprint' });
+                break;
+        }
+        // Add status counts if issues are available
+        const statusCounts = {};
+        if (sprint.issues && sprint.issues.length > 0) {
+            sprint.issues.forEach(issue => {
+                if (!statusCounts[issue.status]) {
+                    statusCounts[issue.status] = 0;
+                }
+                statusCounts[issue.status]++;
+            });
+        }
+        return BaseFormatter.createSummary({
+            status_counts: Object.keys(statusCounts).length > 0 ? statusCounts : undefined,
+            suggested_actions: suggestedActions
+        });
+    }
+}

package/build/utils/text-processing.js

@@ -0,0 +1,343 @@
+import MarkdownIt from 'markdown-it';
+export class TextProcessor {
+    static md = new MarkdownIt();
+    static markdownToAdf(markdown) {
+        const tokens = TextProcessor.md.parse(markdown, {});
+        const content = [];
+        let currentListItems = [];
+        let isInList = false;
+        let listType = null;
+        for (const token of tokens) {
+            switch (token.type) {
+                case 'heading_open':
+                    // Start a new heading block
+                    content.push({
+                        type: 'heading',
+                        attrs: { level: parseInt(token.tag.slice(1)) },
+                        content: []
+                    });
+                    break;
+                case 'heading_close':
+                    break;
+                case 'paragraph_open':
+                    if (!isInList) {
+                        content.push({
+                            type: 'paragraph',
+                            content: []
+                        });
+                    }
+                    break;
+                case 'paragraph_close':
+                    break;
+                case 'bullet_list_open':
+                case 'ordered_list_open':
+                    isInList = true;
+                    listType = token.type === 'bullet_list_open' ? 'bulletList' : 'orderedList';
+                    currentListItems = [];
+                    break;
+                case 'bullet_list_close':
+                case 'ordered_list_close':
+                    if (currentListItems.length > 0) {
+                        content.push({
+                            type: listType,
+                            content: currentListItems
+                        });
+                    }
+                    isInList = false;
+                    listType = null;
+                    currentListItems = [];
+                    break;
+                case 'list_item_open':
+                    currentListItems.push({
+                        type: 'listItem',
+                        content: [{
+                                type: 'paragraph',
+                                content: []
+                            }]
+                    });
+                    break;
+                case 'list_item_close':
+                    break;
+                case 'inline':
+                    const lastBlock = isInList
+                        ? currentListItems[currentListItems.length - 1].content[0]
+                        : content[content.length - 1];
+                    if (!lastBlock)
+                        continue;
+                    let currentText = '';
+                    let marks = [];
+                    for (let i = 0; i < token.children.length; i++) {
+                        const child = token.children[i];
+                        if (child.type === 'text') {
+                            if (currentText && marks.length > 0) {
+                                lastBlock.content.push({
+                                    type: 'text',
+                                    text: currentText,
+                                    marks
+                                });
+                                currentText = '';
+                                marks = [];
+                            }
+                            currentText = child.content;
+                        }
+                        else if (child.type === 'strong_open') {
+                            if (currentText) {
+                                lastBlock.content.push({
+                                    type: 'text',
+                                    text: currentText
+                                });
+                                currentText = '';
+                            }
+                            marks.push({ type: 'strong' });
+                        }
+                        else if (child.type === 'em_open') {
+                            if (currentText) {
+                                lastBlock.content.push({
+                                    type: 'text',
+                                    text: currentText
+                                });
+                                currentText = '';
+                            }
+                            marks.push({ type: 'em' });
+                        }
+                        else if (child.type === 'link_open') {
+                            if (currentText) {
+                                lastBlock.content.push({
+                                    type: 'text',
+                                    text: currentText
+                                });
+                                currentText = '';
+                            }
+                            marks.push({
+                                type: 'link',
+                                attrs: {
+                                    href: child.attrs[0][1]
+                                }
+                            });
+                        }
+                        else if (child.type === 'code_inline') {
+                            if (currentText) {
+                                lastBlock.content.push({
+                                    type: 'text',
+                                    text: currentText
+                                });
+                                currentText = '';
+                            }
+                            lastBlock.content.push({
+                                type: 'text',
+                                text: child.content,
+                                marks: [{ type: 'code' }]
+                            });
+                        }
+                    }
+                    if (currentText) {
+                        lastBlock.content.push({
+                            type: 'text',
+                            text: currentText,
+                            ...(marks.length > 0 && { marks })
+                        });
+                    }
+                    break;
+                case 'hr':
+                    content.push({
+                        type: 'rule'
+                    });
+                    break;
+                case 'hardbreak':
+                    const lastContent = content[content.length - 1];
+                    if (lastContent && lastContent.content) {
+                        lastContent.content.push({
+                            type: 'hardBreak'
+                        });
+                    }
+                    break;
+            }
+        }
+        return {
+            type: 'doc',
+            version: 1,
+            content
+        };
+    }
+    static extractTextFromAdf(node) {
+        if (!node)
+            return '';
+        if (node.type === 'text') {
+            return node.text || '';
+        }
+        if (node.type === 'mention') {
+            return `@${node.attrs?.text?.replace('@', '') || ''}`;
+        }
+        if (node.type === 'hardBreak' || node.type === 'paragraph') {
+            return '\n';
+        }
+        if (node.content) {
+            return node.content
+                .map((child) => TextProcessor.extractTextFromAdf(child))
+                .join('')
+                .replace(/\n{3,}/g, '\n\n'); // Normalize multiple newlines
+        }
+        return '';
+    }
+    static isFieldPopulated(value) {
+        if (value === null || value === undefined)
+            return false;
+        if (typeof value === 'string' && value.trim() === '')
+            return false;
+        if (Array.isArray(value) && value.length === 0)
+            return false;
+        if (typeof value === 'object' && Object.keys(value).length === 0)
+            return false;
+        return true;
+    }
+    static shouldExcludeField(fieldId, fieldValue) {
+        // Exclude system metadata and UI-specific fields
+        const excludePatterns = [
+            'avatar', 'icon', 'self', 'thumbnail', 'timetracking', 'worklog',
+            'watches', 'subtasks', 'attachment', 'aggregateprogress', 'progress',
+            'votes', '_links', 'accountId', 'emailAddress', 'active', 'timeZone',
+            'accountType', '_expands', 'groupIds', 'portalId', 'serviceDeskId',
+            'issueTypeId', 'renderedFields', 'names', 'id', 'expand', 'schema',
+            'operations', 'editmeta', 'changelog', 'versionedRepresentations',
+            'fieldsToInclude', 'properties', 'updateAuthor', 'jsdPublic', 'mediaType',
+            'maxResults', 'total', 'startAt', 'iconUrls', 'issuerestrictions',
+            'shouldDisplay', 'nonEditableReason', 'hasEpicLinkFieldDependency',
+            'showField', 'statusDate', 'statusCategory', 'collection', 'localId',
+            'attrs', 'marks', 'layout', 'version', 'type', 'content', 'table',
+            'tableRow', 'tableCell', 'mediaSingle', 'media', 'heading', 'paragraph',
+            'bulletList', 'listItem', 'orderedList', 'rule', 'inlineCard', 'hardBreak',
+            'workRatio', 'parentLink', 'restrictTo', 'timeToResolution',
+            'timeToFirstResponse', 'slaForInitialResponse'
+        ];
+        // Also exclude email signature related fields and meaningless values
+        if (typeof fieldValue === 'string') {
+            // Email signature patterns
+            const emailPatterns = [
+                'CAUTION:', 'From:', 'Sent:', 'To:', 'Subject:',
+                'Book time to meet with me', 'Best-', 'Best regards',
+                'Kind regards', 'Regards,', 'Mobile', 'Phone', 'Tel:',
+                'www.', 'http://', 'https://', '@.*\\.com$', '^M:',
+                'LLC', 'Inc.', 'Ltd.', 'ForefrontDermatology.com',
+                'Mobile:', 'Office:', 'Direct:'
+            ];
+            // Check for email patterns
+            if (emailPatterns.some(pattern => pattern.startsWith('^') || pattern.endsWith('$')
+                ? new RegExp(pattern).test(fieldValue)
+                : fieldValue.includes(pattern))) {
+                return true;
+            }
+            // Exclude meaningless values
+            if (fieldValue === '-1' ||
+                fieldValue === 'false false' ||
+                fieldValue === '0' ||
+                fieldValue === 'true, ' ||
+                fieldValue === '.' ||
+                /^\s*$/.test(fieldValue)) {
+                return true;
+            }
+        }
+        // Exclude fields that are just punctuation or very short text
+        if (typeof fieldValue === 'string' &&
+            (fieldValue.trim().length <= 1 ||
+                fieldValue.trim() === '.' ||
+                fieldValue.trim() === '-' ||
+                fieldValue.trim() === '_')) {
+            return true;
+        }
+        return excludePatterns.some(pattern => fieldId.toLowerCase().includes(pattern.toLowerCase()));
+    }
+    static formatFieldValue(value, fieldName) {
+        if (value === null || value === undefined)
+            return '';
+        // Handle arrays
+        if (Array.isArray(value)) {
+            // Special handling for comments
+            if (fieldName === 'Comment' || fieldName === 'comments') {
+                return value
+                    .map(comment => {
+                    const author = comment.author?.displayName || 'Unknown';
+                    let body = '';
+                    // Handle rich text content
+                    if (comment.body?.content) {
+                        body = TextProcessor.extractTextFromAdf(comment.body);
+                    }
+                    else {
+                        body = String(comment.body || '');
+                    }
+                    // Clean up email signatures and formatting from body
+                    body = body
+                        .replace(/^[\s\S]*?From:[\s\S]*?Sent:[\s\S]*?To:[\s\S]*?Subject:[\s\S]*?\n/gm, '')
+                        .replace(/^>.*$/gm, '')
+                        .replace(/_{3,}|-{3,}|={3,}/g, '')
+                        .replace(/(?:(?:https?|ftp):\/\/|\b(?:[a-z\d]+\.))(?:(?:[^\s()<>]+|\((?:[^\s()<>]+|(?:\([^\s()<>]+\)))?\))+(?:\((?:[^\s()<>]+|(?:\(?:[^\s()<>]+\)))?\)|[^\s`!()[\]{};:'".,<>?«»""'']))?/g, '')
+                        .replace(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, '')
+                        .replace(/(?:^|\s)(?:Best regards|Kind regards|Regards|Best|Thanks|Thank you|Cheers),.*/gs, '')
+                        .replace(/(?:Mobile|Tel|Phone|Office|Direct):\s*[\d\s.+-]+/g, '')
+                        .replace(/\n{3,}/g, '\n\n')
+                        .trim();
+                    if (!body)
+                        return '';
+                    const created = new Date(comment.created).toLocaleString();
+                    return `${author} (${created}):\n${body}`;
+                })
+                    .filter(comment => comment)
+                    .join('\n\n');
+            }
+            return value
+                .map(item => TextProcessor.formatFieldValue(item))
+                .filter(item => item)
+                .join(', ');
+        }
+        // Handle objects
+        if (typeof value === 'object') {
+            // Handle user objects
+            if (value.displayName) {
+                return value.displayName;
+            }
+            // Handle request type
+            if (value.requestType?.name) {
+                const desc = value.requestType.description ?
+                    ': ' + value.requestType.description.split('.')[0] + '.' : '';
+                return `${value.requestType.name}${desc}`;
+            }
+            // Handle status objects
+            if (value.status && value.statusCategory) {
+                return `${value.status} (${value.statusCategory})`;
+            }
+            // Handle rich text content
+            if (value.content) {
+                return TextProcessor.extractTextFromAdf(value);
+            }
+            // Handle simple name/value objects
+            if (value.name) {
+                return value.name;
+            }
+            if (value.value) {
+                return value.value;
+            }
+            // For other objects, try to extract meaningful values
+            const meaningful = Object.entries(value)
+                .filter(([_k, v]) => !TextProcessor.shouldExcludeField(_k, v) &&
+                v !== null &&
+                v !== undefined &&
+                !_k.startsWith('_'))
+                .map(([_k, v]) => TextProcessor.formatFieldValue(v))
+                .filter(v => v)
+                .join(' ');
+            return meaningful || '';
+        }
+        // Format dates
+        if (fieldName && (fieldName.toLowerCase().includes('date') ||
+            fieldName.toLowerCase().includes('created') ||
+            fieldName.toLowerCase().includes('updated'))) {
+            try {
+                return new Date(value).toLocaleString();
+            }
+            catch {
+                return String(value);
+            }
+        }
+        // Handle primitive values
+        return String(value);
+    }
+}