@aaronsb/jira-cloud-mcp 0.2.0 → 0.2.3

package/README.md

@@ -17,7 +17,7 @@ Add to your MCP settings:
       "env": {
         "JIRA_API_TOKEN": "your-api-token",
         "JIRA_EMAIL": "your-email",
-        "JIRA_HOST": "your-team.atlassian.net"
+        "JIRA_HOST": "https://your-team.atlassian.net"
       }
     }
   }

package/build/client/jira-client.js

@@ -191,9 +191,9 @@ export class JiraClient {
             // Remove escaped quotes from JQL
             const cleanJql = jql.replace(/\\"/g, '"');
             console.error(`Executing JQL search with query: ${cleanJql}`);
-            const searchResults = await this.client.issueSearch.searchForIssuesUsingJql({
+            // Use the new enhanced search API (old /rest/api/3/search was deprecated Oct 2025)
+            const searchResults = await this.client.issueSearch.searchForIssuesUsingJqlEnhancedSearch({
                 jql: cleanJql,
-                startAt,
                 maxResults: Math.min(maxResults, 100),
                 fields: [
                     'summary',
@@ -203,39 +203,43 @@ export class JiraClient {
                     'status',
                     'resolution',
                     'duedate',
+                    'parent',
                     this.customFields.startDate,
                     this.customFields.storyPoints,
                     'timeestimate',
                     'issuelinks',
                 ],
-                expand: 'renderedFields'
+                expand: 'renderedFields',
             });
             const issues = (searchResults.issues || []).map(issue => ({
                 key: issue.key,
-                summary: issue.fields.summary,
+                summary: issue.fields?.summary,
                 description: issue.renderedFields?.description || '',
-                parent: issue.fields.parent?.key || null,
-                assignee: issue.fields.assignee?.displayName || null,
-                reporter: issue.fields.reporter?.displayName || '',
-                status: issue.fields.status?.name || '',
-                resolution: issue.fields.resolution?.name || null,
-                dueDate: issue.fields.duedate || null,
-                startDate: issue.fields[this.customFields.startDate] || null,
-                storyPoints: issue.fields[this.customFields.storyPoints] || null,
-                timeEstimate: issue.fields.timeestimate || null,
-                issueLinks: (issue.fields.issuelinks || []).map(link => ({
+                parent: issue.fields?.parent?.key || null,
+                assignee: issue.fields?.assignee?.displayName || null,
+                reporter: issue.fields?.reporter?.displayName || '',
+                status: issue.fields?.status?.name || '',
+                resolution: issue.fields?.resolution?.name || null,
+                dueDate: issue.fields?.duedate || null,
+                startDate: issue.fields?.[this.customFields.startDate] || null,
+                storyPoints: issue.fields?.[this.customFields.storyPoints] || null,
+                timeEstimate: issue.fields?.timeestimate || null,
+                issueLinks: (issue.fields?.issuelinks || []).map(link => ({
                     type: link.type?.name || '',
                     outward: link.outwardIssue?.key || null,
                     inward: link.inwardIssue?.key || null,
                 })),
             }));
+            // Note: Enhanced search API uses token-based pagination, not offset-based
+            // The total count is not available in the new API
+            const hasMore = !!searchResults.nextPageToken;
             return {
                 issues,
                 pagination: {
                     startAt,
                     maxResults,
-                    total: searchResults.total || 0,
-                    hasMore: (startAt + issues.length) < (searchResults.total || 0)
+                    total: hasMore ? issues.length + 1 : issues.length, // Approximate since total not available
+                    hasMore,
                 }
             };
         }

package/build/handlers/board-handlers.js

@@ -1,5 +1,5 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { BoardFormatter } from '../utils/formatters/index.js';
+import { MarkdownRenderer } from '../mcp/markdown-renderer.js';
 // Helper function to normalize parameter names (support both snake_case and camelCase)
 function normalizeArgs(args) {
     const normalized = {};
@@ -108,7 +108,10 @@ async function handleGetBoard(jiraClient, args) {
     }
     // Convert to BoardData format
     const boardData = {
-        ...board
+        id: board.id,
+        name: board.name,
+        type: board.type,
+        projectName: board.location?.projectName,
     };
     // Handle expansions
     if (expansionOptions.sprints) {
@@ -123,13 +126,24 @@ async function handleGetBoard(jiraClient, args) {
             // Continue even if sprints fail
         }
     }
-    // Format the response
-    const formattedResponse = BoardFormatter.formatBoard(boardData, expansionOptions);
+    // Render to markdown
+    const markdown = MarkdownRenderer.renderBoard({
+        id: boardData.id,
+        name: boardData.name,
+        type: boardData.type,
+        projectName: boardData.projectName,
+        sprints: boardData.sprints?.map((s) => ({
+            id: s.id,
+            name: s.name,
+            state: s.state,
+            goal: s.goal,
+        })),
+    });
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(formattedResponse, null, 2),
+                text: markdown,
             },
         ],
     };
@@ -145,7 +159,10 @@ async function handleListBoards(jiraClient, args) {
     const paginatedBoards = boards.slice(startAt, startAt + maxResults);
     // Convert to BoardData format
     const boardDataList = paginatedBoards.map(board => ({
-        ...board
+        id: board.id,
+        name: board.name,
+        type: board.type,
+        projectName: board.location?.projectName,
     }));
     // If sprints are requested, get them for each board
     if (includeSprints) {
@@ -163,25 +180,35 @@ async function handleListBoards(jiraClient, args) {
             }
         }
     }
-    // Format the response
-    const formattedBoards = boardDataList.map(board => BoardFormatter.formatBoard(board, { sprints: includeSprints }));
-    // Create a response with pagination metadata
-    const response = {
-        data: formattedBoards,
-        _metadata: {
-            pagination: {
-                startAt,
-                maxResults,
-                total: boards.length,
-                hasMore: startAt + maxResults < boards.length,
-            },
-        },
-    };
+    // Convert to markdown renderer format
+    const rendererBoards = boardDataList.map(board => ({
+        id: board.id,
+        name: board.name,
+        type: board.type,
+        projectName: board.projectName,
+        sprints: board.sprints?.map((s) => ({
+            id: s.id,
+            name: s.name,
+            state: s.state,
+            goal: s.goal,
+        })),
+    }));
+    // Render to markdown with pagination
+    let markdown = MarkdownRenderer.renderBoardList(rendererBoards);
+    // Add pagination guidance
+    markdown += '\n\n---\n';
+    if (startAt + maxResults < boards.length) {
+        markdown += `Showing ${startAt + 1}-${startAt + boardDataList.length} of ${boards.length}\n`;
+        markdown += `**Next page:** Use startAt=${startAt + maxResults}`;
+    }
+    else {
+        markdown += `Showing all ${boardDataList.length} board${boardDataList.length !== 1 ? 's' : ''}`;
+    }
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(response, null, 2),
+                text: markdown,
             },
         ],
     };

package/build/handlers/filter-handlers.js

@@ -1,5 +1,5 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { FilterFormatter, SearchFormatter } from '../utils/formatters/index.js';
+import { MarkdownRenderer } from '../mcp/markdown-renderer.js';
 // Helper function to normalize parameter names (support both snake_case and camelCase)
 function normalizeArgs(args) {
     const normalized = {};
@@ -134,14 +134,9 @@ async function handleGetFilter(jiraClient, args) {
             name: filter.name || 'Unnamed Filter',
             owner: filter.owner || 'Unknown',
             favourite: filter.favourite || false,
-            viewUrl: filter.viewUrl || '',
-            description: filter.description || '',
-            jql: filter.jql || '',
-            sharePermissions: filter.sharePermissions?.map(perm => ({
-                type: perm.type,
-                group: perm.group,
-                project: perm.project
-            })) || []
+            viewUrl: filter.viewUrl,
+            description: filter.description,
+            jql: filter.jql,
         };
         // Handle expansions
         if (expansionOptions.issue_count) {
@@ -156,13 +151,13 @@ async function handleGetFilter(jiraClient, args) {
                 // Continue even if issue count fails
             }
         }
-        // Format the response
-        const formattedResponse = FilterFormatter.formatFilter(filterData, expansionOptions);
+        // Render to markdown
+        const markdown = MarkdownRenderer.renderFilter(filterData);
         return {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify(formattedResponse, null, 2),
+                    text: markdown,
                 },
             ],
         };
@@ -212,25 +207,22 @@ async function handleListFilters(jiraClient, args) {
             }
         }
     }
-    // Format the response
-    const formattedFilters = filterDataList.map(filter => FilterFormatter.formatFilter(filter, expansionOptions));
-    // Create a response with pagination metadata
-    const response = {
-        data: formattedFilters,
-        _metadata: {
-            pagination: {
-                startAt,
-                maxResults,
-                total: filters.length,
-                hasMore: startAt + maxResults < filters.length,
-            },
-        },
-    };
+    // Render to markdown with pagination info
+    let markdown = MarkdownRenderer.renderFilterList(filterDataList);
+    // Add pagination guidance
+    markdown += '\n\n---\n';
+    if (startAt + maxResults < filters.length) {
+        markdown += `Showing ${startAt + 1}-${startAt + filterDataList.length} of ${filters.length}\n`;
+        markdown += `**Next page:** Use startAt=${startAt + maxResults}`;
+    }
+    else {
+        markdown += `Showing all ${filterDataList.length} filter${filterDataList.length !== 1 ? 's' : ''}`;
+    }
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(response, null, 2),
+                text: markdown,
             },
         ],
     };
@@ -319,17 +311,18 @@ async function handleExecuteFilter(jiraClient, _args) {
     const filterId = _args.filterId;
     // Get issues for the filter
     const issues = await jiraClient.getFilterIssues(filterId);
+    // Render to markdown
+    const markdown = MarkdownRenderer.renderIssueSearchResults(issues, {
+        startAt: 0,
+        maxResults: issues.length,
+        total: issues.length,
+        hasMore: false,
+    }, `filter = ${filterId}`);
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify({
-                    data: issues,
-                    _metadata: {
-                        filter_id: filterId,
-                        issue_count: issues.length
-                    }
-                }, null, 2),
+                text: markdown,
             },
         ],
     };
@@ -343,24 +336,24 @@ async function handleExecuteJql(jiraClient, args) {
     const maxResults = args.maxResults !== undefined ? args.maxResults : 25;
     try {
         console.error(`Executing JQL search with args:`, JSON.stringify(args, null, 2));
-        // Parse search expansion options
-        const searchExpansionOptions = {};
+        // Parse search expansion options (not currently used but reserved for future)
+        const _searchExpansionOptions = {};
         if (args.expand) {
             for (const expansion of args.expand) {
                 if (['issue_details', 'transitions', 'comments_preview'].includes(expansion)) {
-                    searchExpansionOptions[expansion] = true;
+                    _searchExpansionOptions[expansion] = true;
                 }
             }
         }
         // Execute the search
         const searchResult = await jiraClient.searchIssues(args.jql, startAt, maxResults);
-        // Format the response using the SearchFormatter for enhanced results
-        const formattedResponse = SearchFormatter.formatSearchResult(searchResult, searchExpansionOptions);
+        // Render directly to markdown for token efficiency
+        const markdown = MarkdownRenderer.renderIssueSearchResults(searchResult.issues, searchResult.pagination, args.jql);
         return {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify(formattedResponse, null, 2),
+                    text: markdown,
                 },
             ],
         };

package/build/handlers/issue-handlers.js

@@ -1,5 +1,5 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { IssueFormatter } from '../utils/formatters/index.js';
+import { MarkdownRenderer } from '../mcp/markdown-renderer.js';
 // Helper function to normalize parameter names (support both snake_case and camelCase)
 function normalizeArgs(args) {
     const normalized = {};
@@ -141,13 +141,13 @@ async function handleGetIssue(jiraClient, args) {
     if (expansionOptions.transitions) {
         transitions = await jiraClient.getTransitions(args.issueKey);
     }
-    // Format the response using the IssueFormatter
-    const formattedResponse = IssueFormatter.formatIssue(issue, expansionOptions, transitions);
+    // Render to markdown
+    const markdown = MarkdownRenderer.renderIssue(issue, transitions);
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(formattedResponse, null, 2),
+                text: markdown,
             },
         ],
     };
@@ -163,28 +163,28 @@ async function handleCreateIssue(jiraClient, args) {
         labels: args.labels,
         customFields: args.customFields
     });
-    // Get the created issue to return
+    // Get the created issue and render to markdown
     const createdIssue = await jiraClient.getIssue(result.key, false, false);
-    const formattedResponse = IssueFormatter.formatIssue(createdIssue);
+    const markdown = MarkdownRenderer.renderIssue(createdIssue);
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(formattedResponse, null, 2),
+                text: `# Issue Created\n\n${markdown}`,
             },
         ],
     };
 }
 async function handleUpdateIssue(jiraClient, args) {
     await jiraClient.updateIssue(args.issueKey, args.summary, args.description, args.parent);
-    // Get the updated issue to return
+    // Get the updated issue and render to markdown
     const updatedIssue = await jiraClient.getIssue(args.issueKey, false, false);
-    const formattedResponse = IssueFormatter.formatIssue(updatedIssue);
+    const markdown = MarkdownRenderer.renderIssue(updatedIssue);
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(formattedResponse, null, 2),
+                text: `# Issue Updated\n\n${markdown}`,
             },
         ],
     };
@@ -212,28 +212,28 @@ async function handleDeleteIssue(_jiraClient, _args) {
 }
 async function handleTransitionIssue(jiraClient, args) {
     await jiraClient.transitionIssue(args.issueKey, args.transitionId, args.comment);
-    // Get the updated issue to return
+    // Get the updated issue and render to markdown
     const updatedIssue = await jiraClient.getIssue(args.issueKey, false, false);
-    const formattedResponse = IssueFormatter.formatIssue(updatedIssue);
+    const markdown = MarkdownRenderer.renderIssue(updatedIssue);
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(formattedResponse, null, 2),
+                text: `# Issue Transitioned\n\n${markdown}`,
             },
         ],
     };
 }
 async function handleCommentIssue(jiraClient, args) {
     await jiraClient.addComment(args.issueKey, args.comment);
-    // Get the updated issue with comments to return
+    // Get the updated issue with comments and render to markdown
     const updatedIssue = await jiraClient.getIssue(args.issueKey, true, false);
-    const formattedResponse = IssueFormatter.formatIssue(updatedIssue, { comments: true });
+    const markdown = MarkdownRenderer.renderIssue(updatedIssue);
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(formattedResponse, null, 2),
+                text: `# Comment Added\n\n${markdown}`,
             },
         ],
     };
@@ -242,14 +242,14 @@ async function handleLinkIssue(jiraClient, args) {
     console.error(`Linking issue ${args.issueKey} to ${args.linkedIssueKey} with type ${args.linkType}`);
     // Link the issues
     await jiraClient.linkIssues(args.issueKey, args.linkedIssueKey, args.linkType, args.comment);
-    // Get the updated issue to return
+    // Get the updated issue and render to markdown
     const updatedIssue = await jiraClient.getIssue(args.issueKey, false, false);
-    const formattedResponse = IssueFormatter.formatIssue(updatedIssue);
+    const markdown = MarkdownRenderer.renderIssue(updatedIssue);
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(formattedResponse, null, 2),
+                text: `# Issue Linked\n\n${markdown}`,
             },
         ],
     };

package/build/handlers/project-handlers.js

@@ -1,5 +1,5 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { ProjectFormatter } from '../utils/formatters/index.js';
+import { MarkdownRenderer } from '../mcp/markdown-renderer.js';
 // Helper function to normalize parameter names (support both snake_case and camelCase)
 function normalizeArgs(args) {
     const normalized = {};
@@ -122,12 +122,10 @@ async function handleGetProject(jiraClient, args) {
     }
     // Convert to ProjectData format
     const projectData = {
-        id: project.id,
         key: project.key,
         name: project.name,
-        description: project.description,
-        lead: project.lead,
-        url: project.url
+        description: project.description || undefined,
+        lead: project.lead || undefined,
     };
     // If status counts are requested, get them
     if (includeStatusCounts) {
@@ -140,7 +138,7 @@ async function handleGetProject(jiraClient, args) {
                 const status = issue.status;
                 statusCounts[status] = (statusCounts[status] || 0) + 1;
             }
-            projectData.status_counts = statusCounts;
+            projectData.statusCounts = statusCounts;
         }
         catch (error) {
             console.error(`Error getting status counts for project ${projectKey}:`, error);
@@ -167,20 +165,32 @@ async function handleGetProject(jiraClient, args) {
             // Get recent issues for this project
             const searchResult = await jiraClient.searchIssues(`project = ${projectKey} ORDER BY updated DESC`, 0, 5);
             // Add recent issues to the response
-            projectData.recent_issues = searchResult.issues;
+            projectData.recentIssues = searchResult.issues.map(issue => ({
+                key: issue.key,
+                summary: issue.summary,
+                status: issue.status
+            }));
         }
         catch (error) {
             console.error(`Error getting recent issues for project ${projectKey}:`, error);
             // Continue even if recent issues fail
         }
     }
-    // Format the response
-    const formattedResponse = ProjectFormatter.formatProject(projectData, expansionOptions);
+    // Render to markdown
+    const markdown = MarkdownRenderer.renderProject({
+        key: projectData.key,
+        name: projectData.name,
+        description: projectData.description,
+        lead: projectData.lead,
+        statusCounts: projectData.statusCounts,
+        boards: projectData.boards,
+        recentIssues: projectData.recentIssues,
+    });
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(formattedResponse, null, 2),
+                text: markdown,
             },
         ],
     };
@@ -271,12 +281,10 @@ async function handleListProjects(jiraClient, args) {
     const paginatedProjects = projects.slice(startAt, startAt + maxResults);
     // Convert to ProjectData format
     const projectDataList = paginatedProjects.map(project => ({
-        id: project.id,
         key: project.key,
         name: project.name,
-        description: project.description,
-        lead: project.lead,
-        url: project.url
+        description: project.description || undefined,
+        lead: project.lead || undefined,
     }));
     // If status counts are requested, get them for each project
     if (includeStatusCounts) {
@@ -291,7 +299,7 @@ async function handleListProjects(jiraClient, args) {
                     const status = issue.status;
                     statusCounts[status] = (statusCounts[status] || 0) + 1;
                 }
-                project.status_counts = statusCounts;
+                project.statusCounts = statusCounts;
             }
             catch (error) {
                 console.error(`Error getting status counts for project ${project.key}:`, error);
@@ -299,25 +307,30 @@ async function handleListProjects(jiraClient, args) {
             }
         }
     }
-    // Format the response
-    const formattedProjects = projectDataList.map(project => ProjectFormatter.formatProject(project));
-    // Create a response with pagination metadata
-    const response = {
-        data: formattedProjects,
-        _metadata: {
-            pagination: {
-                startAt,
-                maxResults,
-                total: projects.length,
-                hasMore: startAt + maxResults < projects.length,
-            },
-        },
-    };
+    // Render to markdown with pagination
+    const rendererProjects = projectDataList.map(project => ({
+        key: project.key,
+        name: project.name,
+        description: project.description,
+        lead: project.lead,
+        statusCounts: project.statusCounts,
+    }));
+    // Render to markdown with pagination
+    let markdown = MarkdownRenderer.renderProjectList(rendererProjects);
+    // Add pagination guidance
+    markdown += '\n\n---\n';
+    if (startAt + maxResults < projects.length) {
+        markdown += `Showing ${startAt + 1}-${startAt + projectDataList.length} of ${projects.length}\n`;
+        markdown += `**Next page:** Use startAt=${startAt + maxResults}`;
+    }
+    else {
+        markdown += `Showing all ${projectDataList.length} project${projectDataList.length !== 1 ? 's' : ''}`;
+    }
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(response, null, 2),
+                text: markdown,
             },
         ],
     };

package/build/handlers/search-handlers.js

@@ -1,5 +1,5 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { SearchFormatter } from '../utils/formatters/index.js';
+import { MarkdownRenderer } from '../mcp/markdown-renderer.js';
 // Helper function to normalize parameter names (support both snake_case and camelCase)
 function normalizeArgs(args) {
     const normalized = {};
@@ -67,22 +67,22 @@ export async function setupSearchHandlers(server, jiraClient, request) {
             }
             try {
                 console.error(`Executing search with args:`, JSON.stringify(normalizedArgs, null, 2));
-                // Parse expansion options
-                const expansionOptions = {};
+                // Parse expansion options (reserved for future use)
+                const _expansionOptions = {};
                 if (normalizedArgs.expand) {
                     for (const expansion of normalizedArgs.expand) {
-                        expansionOptions[expansion] = true;
+                        _expansionOptions[expansion] = true;
                     }
                 }
                 // Execute the search
                 const searchResult = await jiraClient.searchIssues(normalizedArgs.jql, normalizedArgs.startAt, normalizedArgs.maxResults);
-                // Format the response using the SearchFormatter
-                const formattedResponse = SearchFormatter.formatSearchResult(searchResult, expansionOptions);
+                // Render to markdown for token efficiency
+                const markdown = MarkdownRenderer.renderIssueSearchResults(searchResult.issues, searchResult.pagination, normalizedArgs.jql);
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: JSON.stringify(formattedResponse, null, 2),
+                            text: markdown,
                         },
                     ],
                 };

package/build/handlers/sprint-handlers.js

@@ -1,5 +1,5 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { SprintFormatter } from '../utils/formatters/sprint-formatter.js';
+import { MarkdownRenderer } from '../mcp/markdown-renderer.js';
 // Helper function to normalize parameter names (support both snake_case and camelCase)
 function normalizeArgs(args) {
     const normalized = {};
@@ -164,24 +164,24 @@ async function handleGetSprint(jiraClient, args) {
     if (expansionOptions.issues) {
         issues = await jiraClient.getSprintIssues(args.sprintId);
     }
-    // Get report if requested
-    let report = undefined;
-    if (expansionOptions.report && sprint.state === 'closed') {
-        report = await jiraClient.getSprintReport(sprint.boardId, args.sprintId);
-    }
-    // Combine data
-    const sprintData = {
-        ...sprint,
-        issues,
-        report,
-    };
-    // Format the response
-    const formattedResponse = SprintFormatter.formatSprint(sprintData, expansionOptions);
+    // Note: Sprint report expansion not yet supported in markdown renderer
+    // Render to markdown
+    const markdown = MarkdownRenderer.renderSprint({
+        id: sprint.id,
+        name: sprint.name,
+        state: sprint.state,
+        boardId: sprint.boardId,
+        goal: sprint.goal,
+        startDate: sprint.startDate,
+        endDate: sprint.endDate,
+        completeDate: sprint.completeDate,
+        issues: issues,
+    });
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(formattedResponse, null, 2),
+                text: markdown,
             },
         ],
     };
@@ -189,13 +189,21 @@ async function handleGetSprint(jiraClient, args) {
 async function handleCreateSprint(jiraClient, args) {
     // Create the sprint
     const response = await jiraClient.createSprint(args.boardId, args.name, args.startDate, args.endDate, args.goal);
-    // Format the response
-    const formattedResponse = SprintFormatter.formatSprint(response);
+    // Render to markdown
+    const markdown = MarkdownRenderer.renderSprint({
+        id: response.id,
+        name: response.name,
+        state: response.state,
+        boardId: response.boardId,
+        goal: response.goal,
+        startDate: response.startDate,
+        endDate: response.endDate,
+    });
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(formattedResponse, null, 2),
+                text: `# Sprint Created\n\n${markdown}`,
             },
         ],
     };
@@ -212,13 +220,21 @@ async function handleUpdateSprint(jiraClient, args) {
         await jiraClient.updateSprint(args.sprintId, args.name, args.goal, args.startDate, args.endDate, args.state);
         // Get the updated sprint
         const updatedSprint = await jiraClient.getSprint(args.sprintId);
-        // Format the response
-        const formattedResponse = SprintFormatter.formatSprint(updatedSprint);
+        // Render to markdown
+        const markdown = MarkdownRenderer.renderSprint({
+            id: updatedSprint.id,
+            name: updatedSprint.name,
+            state: updatedSprint.state,
+            boardId: updatedSprint.boardId,
+            goal: updatedSprint.goal,
+            startDate: updatedSprint.startDate,
+            endDate: updatedSprint.endDate,
+        });
         return {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify(formattedResponse, null, 2),
+                    text: `# Sprint Updated\n\n${markdown}`,
                 },
             ],
         };
@@ -244,10 +260,7 @@ async function handleDeleteSprint(jiraClient, args) {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify({
-                    success: true,
-                    message: `Sprint ${args.sprintId} has been deleted successfully.`,
-                }, null, 2),
+                text: `# Sprint Deleted\n\nSprint ${args.sprintId} has been deleted successfully.`,
             },
         ],
     };
@@ -258,17 +271,46 @@ async function handleListSprints(jiraClient, args) {
     const maxResults = args.maxResults !== undefined ? args.maxResults : 50;
     // Get sprints
     const response = await jiraClient.listSprints(args.boardId, args.state, startAt, maxResults);
-    // Format the response
-    const formattedResponse = SprintFormatter.formatSprintList(response.sprints, {
-        startAt,
-        maxResults,
-        total: response.total,
-    });
+    // Render sprints to markdown
+    const lines = [];
+    lines.push(`# Sprints (${response.total})`);
+    if (args.state) {
+        lines.push(`**Filter:** ${args.state}`);
+    }
+    lines.push('');
+    // Group by state
+    const byState = {};
+    for (const sprint of response.sprints) {
+        const state = sprint.state || 'unknown';
+        if (!byState[state])
+            byState[state] = [];
+        byState[state].push(sprint);
+    }
+    for (const [state, sprints] of Object.entries(byState)) {
+        const stateIcon = state === 'active' ? '[>]' : state === 'closed' ? '[x]' : '[ ]';
+        lines.push(`## ${state.charAt(0).toUpperCase() + state.slice(1)} ${stateIcon}`);
+        for (const sprint of sprints) {
+            lines.push(`- **${sprint.name}** (id: ${sprint.id})`);
+            if (sprint.goal) {
+                lines.push(`  Goal: ${sprint.goal.substring(0, 80)}${sprint.goal.length > 80 ? '...' : ''}`);
+            }
+        }
+        lines.push('');
+    }
+    // Pagination
+    lines.push('---');
+    if (startAt + maxResults < response.total) {
+        lines.push(`Showing ${startAt + 1}-${startAt + response.sprints.length} of ${response.total}`);
+        lines.push(`**Next page:** Use startAt=${startAt + maxResults}`);
+    }
+    else {
+        lines.push(`Showing all ${response.sprints.length} sprint${response.sprints.length !== 1 ? 's' : ''}`);
+    }
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(formattedResponse, null, 2),
+                text: lines.join('\n'),
             },
         ],
     };
@@ -291,18 +333,22 @@ async function handleManageIssues(jiraClient, args) {
         // Get the updated sprint with issues
         const sprint = await jiraClient.getSprint(args.sprintId);
         const issues = await jiraClient.getSprintIssues(args.sprintId);
-        // Combine data
-        const sprintData = {
-            ...sprint,
-            issues,
-        };
-        // Format the response
-        const formattedResponse = SprintFormatter.formatSprint(sprintData, { issues: true });
+        // Render to markdown
+        const markdown = MarkdownRenderer.renderSprint({
+            id: sprint.id,
+            name: sprint.name,
+            state: sprint.state,
+            boardId: sprint.boardId,
+            goal: sprint.goal,
+            startDate: sprint.startDate,
+            endDate: sprint.endDate,
+            issues: issues,
+        });
         return {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify(formattedResponse, null, 2),
+                    text: `# Sprint Issues Updated\n\n${markdown}`,
                 },
             ],
         };

package/build/mcp/markdown-renderer.js

@@ -0,0 +1,422 @@
+/**
+ * Markdown renderer for MCP tool responses
+ *
+ * Converts structured JSON responses to token-efficient markdown
+ * that's optimized for AI assistant consumption.
+ *
+ * Design principles:
+ * - Minimal tokens, maximum clarity
+ * - Embedded navigation hints (suggested next actions)
+ * - Human-readable pagination guidance
+ * - Plain text structure over decorative formatting
+ */
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Format a date string to a more readable format
+ */
+function formatDate(dateStr) {
+    if (!dateStr)
+        return 'Not set';
+    const date = new Date(dateStr);
+    return date.toLocaleDateString('en-US', {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric'
+    });
+}
+/**
+ * Format status with visual indicator
+ */
+function formatStatus(status) {
+    const statusIcons = {
+        'Done': '[x]',
+        'Closed': '[x]',
+        'Resolved': '[x]',
+        'In Progress': '[>]',
+        'In Review': '[>]',
+        'To Do': '[ ]',
+        'Open': '[ ]',
+        'Backlog': '[-]',
+    };
+    const icon = statusIcons[status] || '[?]';
+    return `${icon} ${status}`;
+}
+/**
+ * Truncate text to a maximum length with ellipsis
+ */
+function truncate(text, maxLength = 150) {
+    if (!text)
+        return '';
+    const cleaned = text.replace(/\n+/g, ' ').trim();
+    if (cleaned.length <= maxLength)
+        return cleaned;
+    return cleaned.substring(0, maxLength).trim() + '...';
+}
+/**
+ * Strip HTML tags for plain text display
+ */
+function stripHtml(html) {
+    return html
+        .replace(/<[^>]*>/g, '')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+// ============================================================================
+// Issue Rendering
+// ============================================================================
+/**
+ * Render a single issue as markdown
+ */
+export function renderIssue(issue, transitions) {
+    const lines = [];
+    lines.push(`# ${issue.key}: ${issue.summary}`);
+    lines.push('');
+    // Core fields
+    lines.push(`**Status:** ${formatStatus(issue.status)}`);
+    if (issue.assignee) {
+        lines.push(`**Assignee:** ${issue.assignee}`);
+    }
+    else {
+        lines.push(`**Assignee:** Unassigned`);
+    }
+    lines.push(`**Reporter:** ${issue.reporter}`);
+    if (issue.parent) {
+        lines.push(`**Parent:** ${issue.parent}`);
+    }
+    if (issue.dueDate) {
+        lines.push(`**Due:** ${formatDate(issue.dueDate)}`);
+    }
+    if (issue.storyPoints) {
+        lines.push(`**Points:** ${issue.storyPoints}`);
+    }
+    if (issue.resolution) {
+        lines.push(`**Resolution:** ${issue.resolution}`);
+    }
+    // Description (truncated for token efficiency)
+    if (issue.description) {
+        lines.push('');
+        lines.push('## Description');
+        const desc = stripHtml(issue.description);
+        lines.push(truncate(desc, 300));
+    }
+    // Issue links
+    if (issue.issueLinks && issue.issueLinks.length > 0) {
+        lines.push('');
+        lines.push('## Links');
+        for (const link of issue.issueLinks) {
+            if (link.outward) {
+                lines.push(`- ${link.type} -> ${link.outward}`);
+            }
+            if (link.inward) {
+                lines.push(`- ${link.type} <- ${link.inward}`);
+            }
+        }
+    }
+    // Comments (if present)
+    if (issue.comments && issue.comments.length > 0) {
+        lines.push('');
+        lines.push(`## Comments (${issue.comments.length})`);
+        // Show last 3 comments
+        const recentComments = issue.comments.slice(-3);
+        for (const comment of recentComments) {
+            lines.push(`- **${comment.author}** (${formatDate(comment.created)}): ${truncate(stripHtml(comment.body), 100)}`);
+        }
+        if (issue.comments.length > 3) {
+            lines.push(`  ... and ${issue.comments.length - 3} more comments`);
+        }
+    }
+    // Available transitions
+    if (transitions && transitions.length > 0) {
+        lines.push('');
+        lines.push('## Available Actions');
+        for (const t of transitions) {
+            lines.push(`- **${t.name}** -> ${t.to.name} (id: ${t.id})`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Render issue search results as markdown
+ */
+export function renderIssueSearchResults(issues, pagination, jql) {
+    const lines = [];
+    // Header
+    if (jql) {
+        lines.push(`# Search Results`);
+        lines.push(`**JQL:** \`${jql}\``);
+    }
+    else {
+        lines.push('# Issues');
+    }
+    lines.push(`Found ${pagination.total} issue${pagination.total !== 1 ? 's' : ''}`);
+    lines.push('');
+    // Status summary
+    const statusCounts = {};
+    for (const issue of issues) {
+        statusCounts[issue.status] = (statusCounts[issue.status] || 0) + 1;
+    }
+    if (Object.keys(statusCounts).length > 1) {
+        lines.push('**By Status:** ' + Object.entries(statusCounts)
+            .map(([status, count]) => `${status}: ${count}`)
+            .join(', '));
+        lines.push('');
+    }
+    // Issues list
+    for (let i = 0; i < issues.length; i++) {
+        const issue = issues[i];
+        const num = pagination.startAt + i + 1;
+        lines.push(`## ${num}. ${issue.key}: ${issue.summary}`);
+        lines.push(`${formatStatus(issue.status)} | ${issue.assignee || 'Unassigned'}`);
+        if (issue.dueDate) {
+            lines.push(`Due: ${formatDate(issue.dueDate)}`);
+        }
+        if (issue.description) {
+            const desc = stripHtml(issue.description);
+            if (desc.length > 0) {
+                lines.push(`> ${truncate(desc, 120)}`);
+            }
+        }
+        lines.push('');
+    }
+    // Pagination guidance
+    lines.push('---');
+    if (pagination.hasMore) {
+        const nextOffset = pagination.startAt + pagination.maxResults;
+        lines.push(`Showing ${pagination.startAt + 1}-${pagination.startAt + issues.length} of ${pagination.total}`);
+        lines.push(`**Next page:** Use startAt=${nextOffset}`);
+    }
+    else if (pagination.startAt > 0) {
+        lines.push(`Showing ${pagination.startAt + 1}-${pagination.startAt + issues.length} of ${pagination.total} (last page)`);
+    }
+    else {
+        lines.push(`Showing all ${issues.length} result${issues.length !== 1 ? 's' : ''}`);
+    }
+    return lines.join('\n');
+}
+export function renderProject(project) {
+    const lines = [];
+    lines.push(`# ${project.key}: ${project.name}`);
+    lines.push('');
+    if (project.lead) {
+        lines.push(`**Lead:** ${project.lead}`);
+    }
+    if (project.projectTypeKey) {
+        lines.push(`**Type:** ${project.projectTypeKey}`);
+    }
+    if (project.description) {
+        lines.push('');
+        lines.push(truncate(stripHtml(project.description), 200));
+    }
+    // Status counts
+    if (project.statusCounts && Object.keys(project.statusCounts).length > 0) {
+        lines.push('');
+        lines.push('## Issue Summary');
+        const total = Object.values(project.statusCounts).reduce((a, b) => a + b, 0);
+        lines.push(`Total: ${total} issues`);
+        for (const [status, count] of Object.entries(project.statusCounts)) {
+            lines.push(`- ${status}: ${count}`);
+        }
+    }
+    // Boards
+    if (project.boards && project.boards.length > 0) {
+        lines.push('');
+        lines.push('## Boards');
+        for (const board of project.boards) {
+            lines.push(`- ${board.name} (${board.type}, id: ${board.id})`);
+        }
+    }
+    // Recent issues
+    if (project.recentIssues && project.recentIssues.length > 0) {
+        lines.push('');
+        lines.push('## Recent Issues');
+        for (const issue of project.recentIssues) {
+            lines.push(`- ${issue.key}: ${issue.summary} [${issue.status}]`);
+        }
+    }
+    return lines.join('\n');
+}
+export function renderProjectList(projects) {
+    const lines = [];
+    lines.push(`# Projects (${projects.length})`);
+    lines.push('');
+    for (const project of projects) {
+        lines.push(`## ${project.key}: ${project.name}`);
+        if (project.lead) {
+            lines.push(`Lead: ${project.lead}`);
+        }
+        if (project.description) {
+            lines.push(`> ${truncate(stripHtml(project.description), 100)}`);
+        }
+        if (project.statusCounts) {
+            const total = Object.values(project.statusCounts).reduce((a, b) => a + b, 0);
+            lines.push(`Issues: ${total}`);
+        }
+        lines.push('');
+    }
+    lines.push('---');
+    lines.push(`Tip: Use manage_jira_project with operation="get" and projectKey="KEY" for details`);
+    return lines.join('\n');
+}
+export function renderBoard(board) {
+    const lines = [];
+    lines.push(`# Board: ${board.name}`);
+    lines.push(`**ID:** ${board.id}`);
+    lines.push(`**Type:** ${board.type}`);
+    if (board.projectKey) {
+        lines.push(`**Project:** ${board.projectKey} (${board.projectName || ''})`);
+    }
+    if (board.sprints && board.sprints.length > 0) {
+        lines.push('');
+        lines.push('## Sprints');
+        for (const sprint of board.sprints) {
+            const stateIcon = sprint.state === 'active' ? '[>]' : sprint.state === 'closed' ? '[x]' : '[ ]';
+            lines.push(`- ${stateIcon} ${sprint.name} (id: ${sprint.id})`);
+            if (sprint.goal) {
+                lines.push(`  Goal: ${truncate(sprint.goal, 80)}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+export function renderBoardList(boards) {
+    const lines = [];
+    lines.push(`# Boards (${boards.length})`);
+    lines.push('');
+    // Group by type
+    const byType = {};
+    for (const board of boards) {
+        const type = board.type || 'other';
+        if (!byType[type])
+            byType[type] = [];
+        byType[type].push(board);
+    }
+    for (const [type, typeBoards] of Object.entries(byType)) {
+        lines.push(`## ${type.charAt(0).toUpperCase() + type.slice(1)} Boards`);
+        for (const board of typeBoards) {
+            lines.push(`- **${board.name}** (id: ${board.id})${board.projectKey ? ` - ${board.projectKey}` : ''}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function renderSprint(sprint) {
+    const lines = [];
+    const stateIcon = sprint.state === 'active' ? '[ACTIVE]' : sprint.state === 'closed' ? '[CLOSED]' : '[FUTURE]';
+    lines.push(`# Sprint: ${sprint.name} ${stateIcon}`);
+    lines.push(`**ID:** ${sprint.id}`);
+    lines.push(`**Board:** ${sprint.boardId}`);
+    if (sprint.startDate) {
+        lines.push(`**Started:** ${formatDate(sprint.startDate)}`);
+    }
+    if (sprint.endDate) {
+        lines.push(`**Ends:** ${formatDate(sprint.endDate)}`);
+    }
+    if (sprint.completeDate) {
+        lines.push(`**Completed:** ${formatDate(sprint.completeDate)}`);
+    }
+    if (sprint.goal) {
+        lines.push('');
+        lines.push('## Goal');
+        lines.push(sprint.goal);
+    }
+    if (sprint.issues && sprint.issues.length > 0) {
+        lines.push('');
+        lines.push(`## Issues (${sprint.issues.length})`);
+        // Group by status
+        const byStatus = {};
+        for (const issue of sprint.issues) {
+            const status = issue.status || 'Unknown';
+            if (!byStatus[status])
+                byStatus[status] = [];
+            byStatus[status].push(issue);
+        }
+        for (const [status, statusIssues] of Object.entries(byStatus)) {
+            lines.push(`### ${status} (${statusIssues.length})`);
+            for (const issue of statusIssues) {
+                lines.push(`- ${issue.key}: ${issue.summary}${issue.assignee ? ` [${issue.assignee}]` : ''}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+export function renderFilter(filter) {
+    const lines = [];
+    lines.push(`# Filter: ${filter.name}`);
+    lines.push(`**ID:** ${filter.id}`);
+    lines.push(`**Owner:** ${filter.owner}`);
+    lines.push(`**Favorite:** ${filter.favourite ? 'Yes' : 'No'}`);
+    if (filter.jql) {
+        lines.push('');
+        lines.push('## JQL');
+        lines.push('```');
+        lines.push(filter.jql);
+        lines.push('```');
+    }
+    if (filter.description) {
+        lines.push('');
+        lines.push('## Description');
+        lines.push(filter.description);
+    }
+    if (filter.issueCount !== undefined) {
+        lines.push('');
+        lines.push(`**Matches:** ${filter.issueCount} issues`);
+    }
+    lines.push('');
+    lines.push('---');
+    lines.push(`Tip: Use manage_jira_filter with operation="execute_filter" and filterId="${filter.id}" to run this filter`);
+    return lines.join('\n');
+}
+export function renderFilterList(filters) {
+    const lines = [];
+    lines.push(`# Filters (${filters.length})`);
+    lines.push('');
+    // Separate favorites
+    const favorites = filters.filter(f => f.favourite);
+    const others = filters.filter(f => !f.favourite);
+    if (favorites.length > 0) {
+        lines.push('## Favorites');
+        for (const filter of favorites) {
+            lines.push(`- **${filter.name}** (id: ${filter.id}) - ${filter.owner}`);
+        }
+        lines.push('');
+    }
+    if (others.length > 0) {
+        lines.push('## Other Filters');
+        for (const filter of others) {
+            lines.push(`- ${filter.name} (id: ${filter.id}) - ${filter.owner}`);
+        }
+    }
+    return lines.join('\n');
+}
+// ============================================================================
+// Export convenience object
+// ============================================================================
+export const MarkdownRenderer = {
+    // Issues
+    renderIssue,
+    renderIssueSearchResults,
+    // Projects
+    renderProject,
+    renderProjectList,
+    // Boards
+    renderBoard,
+    renderBoardList,
+    // Sprints
+    renderSprint,
+    // Filters
+    renderFilter,
+    renderFilterList,
+    // Helpers (exposed for custom use)
+    helpers: {
+        formatDate,
+        formatStatus,
+        truncate,
+        stripHtml,
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaronsb/jira-cloud-mcp",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Model Context Protocol (MCP) server for Jira Cloud - enables AI assistants to interact with Jira",
   "type": "module",
   "bin": {