@crypto512/jicon-mcp 2.2.1 → 2.3.19

package/dist/jira/activity-tools.js

@@ -7,11 +7,16 @@
  * - "Any blockers in recent discussions?"
  * - "Summarize team activity this month"
  * - "Analyze Epic PROJ-123 for progress and velocity"
+ *
+ * All tool handlers use session-scoped clients via getSessionJiraClient()
+ * which provides per-session caching and credential isolation.
  */
 import { z } from "zod";
-import { formatSuccessDirect, formatError, isApiError, getMaxOutputSize } from "../utils/response-formatter.js";
+import { getSessionJiraClient } from "../session/context.js";
+import { formatSuccessDirect, formatSuccessJson, formatError, isApiError, getMaxOutputSize, getMaxApiResults, getDefaultPeriod } from "../utils/response-formatter.js";
 import { parseSince } from "../utils/date-tools.js";
 import { formatTimeSpent } from "../utils/time-formatter.js";
+import { formatCommentMetadata } from "./formatters.js";
 /**
  * Build JQL from flexible scoping parameters
  */
@@ -25,7 +30,7 @@ function buildScopingJql(params) {
     if (params.projectKey) {
         return `project = ${params.projectKey}`;
     }
-    throw new Error("At least one scoping parameter required: projectKey, jql, or issueKeys");
+    throw new Error('At least one scoping parameter required: projectKey, jql, or issueKeys. Call help(topic="analysis") for scoping guide.');
 }
 /**
  * Format a date string for display (e.g., "Jan 28 14:30")
@@ -82,11 +87,73 @@ function truncateText(text, maxLength) {
     return text.substring(0, maxLength - 3) + "...";
 }
 /**
- * Create activity tools with a client getter function
+ * Sanitize text for use in markdown tables.
+ * Removes/replaces characters that break table formatting.
  */
-export function createActivityTools(getClient) {
+function sanitizeForTable(text) {
+    if (!text)
+        return "";
+    return text
+        .replace(/<br\s*\/?>/gi, " ") // Replace <br> tags with space
+        .replace(/<[^>]+>/g, "") // Remove other HTML tags
+        .replace(/\|/g, "\\|") // Escape pipe characters
+        .replace(/\n/g, " ") // Replace newlines with space
+        .replace(/\s+/g, " ") // Collapse multiple spaces
+        .trim();
+}
+/**
+ * Convert HTML content to Markdown for free-text display (comments, descriptions).
+ * Preserves line breaks and basic formatting.
+ */
+function htmlToMarkdown(text) {
+    if (!text)
+        return "";
+    return text
+        // Convert block elements to double newlines
+        .replace(/<\/p>\s*<p[^>]*>/gi, "\n\n")
+        .replace(/<p[^>]*>/gi, "")
+        .replace(/<\/p>/gi, "\n\n")
+        .replace(/<\/div>\s*<div[^>]*>/gi, "\n\n")
+        .replace(/<div[^>]*>/gi, "")
+        .replace(/<\/div>/gi, "\n")
+        // Convert line breaks
+        .replace(/<br\s*\/?>/gi, "\n")
+        // Convert lists
+        .replace(/<li[^>]*>/gi, "• ")
+        .replace(/<\/li>/gi, "\n")
+        .replace(/<\/?[uo]l[^>]*>/gi, "\n")
+        // Convert basic formatting
+        .replace(/<strong[^>]*>|<b[^>]*>/gi, "**")
+        .replace(/<\/strong>|<\/b>/gi, "**")
+        .replace(/<em[^>]*>|<i[^>]*>/gi, "_")
+        .replace(/<\/em>|<\/i>/gi, "_")
+        .replace(/<code[^>]*>/gi, "`")
+        .replace(/<\/code>/gi, "`")
+        // Convert links: <a href="url">text</a> → [text](url)
+        .replace(/<a[^>]*href="([^"]*)"[^>]*>([^<]*)<\/a>/gi, "[$2]($1)")
+        // Remove remaining HTML tags
+        .replace(/<[^>]+>/g, "")
+        // Decode common HTML entities
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&nbsp;/g, " ")
+        // Clean up excessive whitespace while preserving intentional line breaks
+        .replace(/[ \t]+/g, " ") // Collapse horizontal whitespace
+        .replace(/\n{3,}/g, "\n\n") // Max 2 consecutive newlines
+        .trim();
+}
+/**
+ * Create activity tools using session-scoped clients
+ *
+ * Tools automatically use the JiraClient from the current session context,
+ * which provides per-session caching and credential isolation.
+ */
+export function createActivityTools() {
     const requireClient = () => {
-        const client = getClient();
+        const client = getSessionJiraClient();
         if (!client) {
             throw new Error("Jira is not configured. Provide JIRA_URL and JIRA_API_TOKEN environment variables, or pass credentials via X-Jira-Url and X-Jira-Token headers.");
         }
@@ -104,14 +171,14 @@ Fetches comments, status changes, priority changes, and assignee changes. Ideal
 REQUIRES: At least one scoping parameter (projectKey, jql, or issueKeys)
 RETURNS: Markdown-formatted activity digest with pre-computed summary
 
-Example: jira_get_activity_digest(projectKey="ACME", since="7d")`,
+Example: jira_get_activity_digest(projectKey="ACME", since="30d")`,
             inputSchema: z.object({
                 // Flexible scoping - at least one required
                 projectKey: z.string().optional().describe("Filter by project key"),
                 jql: z.string().optional().describe("Full JQL query for flexible scoping"),
                 issueKeys: z.array(z.string()).optional().describe("Specific issue keys to include"),
                 // Time range
-                since: z.string().optional().describe('Time range: "1d", "7d", "30d", or ISO date (default: "7d")'),
+                since: z.string().optional().describe('Time range: "7d", "30d", "365d", or ISO date (default: "30d"). Provide explicitly for accurate results.'),
                 // Activity types
                 includeComments: z.boolean().optional().describe("Include comments (default: true)"),
                 includeStatusChanges: z.boolean().optional().describe("Include status changes (default: true)"),
@@ -119,14 +186,12 @@ Example: jira_get_activity_digest(projectKey="ACME", since="7d")`,
                 includeAssigneeChanges: z.boolean().optional().describe("Include assignee changes (default: true)"),
                 // Output control
                 maxActivities: z.number().optional().describe("Maximum activities to return (default: 50)"),
-                commentMaxLength: z.number().optional().describe("Max length for comment text (default: 500)"),
             }),
             handler: async (args) => {
                 try {
-                    const since = args.since || "7d";
+                    const since = args.since || getDefaultPeriod();
                     const { dateFrom, dateTo } = parseSince(since);
                     const maxActivities = args.maxActivities ?? 50;
-                    const commentMaxLength = args.commentMaxLength ?? 500;
                     // Build scoping JQL
                     const scopeJql = buildScopingJql({
                         projectKey: args.projectKey,
@@ -207,7 +272,7 @@ Example: jira_get_activity_digest(projectKey="ACME", since="7d")`,
                                     timestamp: comment.created,
                                     author: comment.author.displayName,
                                     details: {
-                                        body: truncateText(comment.body, commentMaxLength),
+                                        body: htmlToMarkdown(comment.body),
                                     },
                                 });
                             }
@@ -343,36 +408,36 @@ Example: jira_get_activity_digest(projectKey="ACME", since="7d")`,
             },
         },
         jira_get_recent_comments: {
-            description: `Get comments across multiple issues for discussion analysis. Returns DIRECTLY (not buffered).
+            description: `Get comments across multiple issues for analysis. Returns buffered data.
 
 Ideal for:
+- "Who commented the most on project X?"
 - "Show me recent discussions about authentication"
-- "What are people saying about the new feature?"
 - "Find comments mentioning blockers"
 
 REQUIRES: At least one scoping parameter (projectKey, jql, or issueKeys)
-RETURNS: Markdown-formatted comments with issue context
+IMPORTANT: Always provide since — default is 30d. Use "365d" or ISO date for longer history.
+RETURNS: bufferId with comments array (issueKey, author, body, created)
+NEXT: buffer_transform for stats/tables, buffer_grep to search
 
-Example: jira_get_recent_comments(projectKey="ACME", since="7d")`,
+Example: jira_get_recent_comments(projectKey="ACME", since="365d", maxComments=5000)`,
             inputSchema: z.object({
                 // Flexible scoping
                 projectKey: z.string().optional().describe("Filter by project key"),
                 jql: z.string().optional().describe("Full JQL query for flexible scoping"),
                 issueKeys: z.array(z.string()).optional().describe("Specific issue keys to include"),
                 // Time
-                since: z.string().optional().describe('Time range: "1d", "7d", "30d", or ISO date (default: "7d")'),
+                since: z.string().optional().describe('Time range: "7d", "30d", "365d", or ISO date (default: "30d"). Provide explicitly for accurate results.'),
                 // Filtering
                 authorKey: z.string().optional().describe("Filter by comment author username"),
                 // Output
-                maxComments: z.number().optional().describe("Maximum comments to return (default: 30)"),
-                includeContext: z.boolean().optional().describe("Include issue summary/status (default: true)"),
+                maxComments: z.number().optional().describe("Maximum comments to return (default: all)"),
             }),
             handler: async (args) => {
                 try {
-                    const since = args.since || "7d";
+                    const since = args.since || getDefaultPeriod();
                     const { dateFrom, dateTo } = parseSince(since);
-                    const maxComments = args.maxComments ?? 30;
-                    const includeContext = args.includeContext !== false;
+                    const maxComments = args.maxComments ?? getMaxApiResults();
                     // Build scoping JQL
                     const scopeJql = buildScopingJql({
                         projectKey: args.projectKey,
@@ -382,11 +447,13 @@ Example: jira_get_recent_comments(projectKey="ACME", since="7d")`,
                     // Add date filter for updated issues (comments update the issue)
                     const fullJql = `${scopeJql} AND updated >= "${dateFrom}" ORDER BY updated DESC`;
                     // Search for issues
-                    const searchResult = await requireClient().searchIssuesAll(fullJql, ["summary", "status"], 100);
+                    const searchResult = await requireClient().searchIssuesAll(fullJql, ["summary", "status"], getMaxApiResults());
                     if (searchResult.issues.length === 0) {
-                        return formatSuccessDirect({
-                            _directContent: true,
-                            content: `# Recent Comments\n\nNo issues with recent activity found for the specified scope.`,
+                        return formatSuccessJson([], {
+                            resourceType: "jira_comments",
+                            schemaType: "jira_comment",
+                            title: "Recent comments: no issues with recent activity found",
+                            totalComments: 0,
                         });
                     }
                     // Get comments for all issues
@@ -413,54 +480,28 @@ Example: jira_get_recent_comments(projectKey="ACME", since="7d")`,
                     // Sort by date (most recent first)
                     allComments.sort((a, b) => new Date(b.comment.created).getTime() - new Date(a.comment.created).getTime());
                     const limitedComments = allComments.slice(0, maxComments);
-                    // Group by issue
-                    const byIssue = new Map();
-                    for (const { issueKey, issue, comment } of limitedComments) {
-                        if (!byIssue.has(issueKey)) {
-                            byIssue.set(issueKey, { issue, comments: [] });
-                        }
-                        byIssue.get(issueKey).comments.push(comment);
-                    }
-                    // Build markdown output
+                    // Flatten comments to jira_comment schema with issue context
+                    const comments = limitedComments.map(({ issueKey, issue, comment }) => formatCommentMetadata(comment, {
+                        issueKey,
+                        issueSummary: issue.fields.summary || undefined,
+                    }));
                     const scopeDesc = args.projectKey
                         ? `Project ${args.projectKey}`
                         : args.jql
                             ? `JQL: ${args.jql.substring(0, 50)}...`
                             : `${args.issueKeys?.length || 0} issues`;
-                    const lines = [
-                        `# Recent Comments: ${scopeDesc}`,
-                        `**Period**: ${dateFrom} to ${dateTo}`,
-                        "",
-                    ];
-                    // Track unique authors
-                    const authors = new Set();
-                    for (const [issueKey, data] of byIssue) {
-                        const statusName = data.issue.fields.status?.name || "Unknown";
-                        const contextInfo = includeContext ? ` [${statusName}]` : "";
-                        lines.push(`## ${issueKey}: ${data.issue.fields.summary}${contextInfo}`);
-                        for (const comment of data.comments) {
-                            authors.add(comment.author.displayName);
-                            const dateTime = formatDisplayDateTime(comment.created);
-                            // Truncate long comments
-                            const body = truncateText(comment.body, 500);
-                            const formattedBody = body.includes("\n")
-                                ? body.split("\n").map((l, i) => (i === 0 ? l : "  " + l)).join("\n")
-                                : body;
-                            lines.push(`- @${comment.author.displayName} (${dateTime}): "${formattedBody}"`);
-                        }
-                        lines.push("");
-                    }
-                    // Add summary
-                    lines.push("---");
-                    lines.push(`**Total**: ${limitedComments.length} comments across ${byIssue.size} issues`);
-                    lines.push(`**Unique authors**: ${authors.size}`);
-                    if (allComments.length > maxComments) {
-                        lines.push(`**Note**: Showing ${maxComments} of ${allComments.length} comments`);
-                    }
-                    const output = lines.join("\n");
-                    return formatSuccessDirect({
-                        _directContent: true,
-                        content: output,
+                    return formatSuccessJson(comments, {
+                        resourceType: "jira_comments",
+                        schemaType: "jira_comment",
+                        title: `Recent comments: ${scopeDesc} (${dateFrom} to ${dateTo})`,
+                        totalComments: allComments.length,
+                        info: {
+                            period: `${dateFrom} to ${dateTo}`,
+                            since,
+                            issuesSearched: searchResult.issues.length,
+                            totalComments: allComments.length,
+                            ...(allComments.length > maxComments && { limited: `Showing ${maxComments} of ${allComments.length} (increase maxComments)` }),
+                        },
                     });
                 }
                 catch (error) {
@@ -479,14 +520,14 @@ Ideal for:
 REQUIRES: At least one scoping parameter (projectKey, jql, or issueKeys)
 RETURNS: Markdown-formatted changelog with pre-computed summary
 
-Example: jira_get_changelog(projectKey="ACME", since="7d", fields=["status", "priority"])`,
+Example: jira_get_changelog(projectKey="ACME", since="30d", fields=["status", "priority"])`,
             inputSchema: z.object({
                 // Flexible scoping
                 projectKey: z.string().optional().describe("Filter by project key"),
                 jql: z.string().optional().describe("Full JQL query for flexible scoping"),
                 issueKeys: z.array(z.string()).optional().describe("Specific issue keys to include"),
                 // Time
-                since: z.string().optional().describe('Time range: "1d", "7d", "30d", or ISO date (default: "7d")'),
+                since: z.string().optional().describe('Time range: "7d", "30d", "365d", or ISO date (default: "30d"). Provide explicitly for accurate results.'),
                 // Filtering
                 fields: z.array(z.string()).optional().describe('Fields to track (default: ["status", "priority", "assignee", "resolution"])'),
                 // Output
@@ -494,7 +535,7 @@ Example: jira_get_changelog(projectKey="ACME", since="7d", fields=["status", "pr
             }),
             handler: async (args) => {
                 try {
-                    const since = args.since || "7d";
+                    const since = args.since || getDefaultPeriod();
                     const { dateFrom, dateTo } = parseSince(since);
                     const userFields = args.fields || ["status", "priority", "assignee", "resolution"];
                     const maxChanges = args.maxChanges ?? 50;
@@ -867,7 +908,7 @@ Example: jira_analyze_epic(issueKey="PROJ-100")`,
                                     issueKey,
                                     author: comment.author.displayName,
                                     date: comment.created,
-                                    body: truncateText(comment.body, 300),
+                                    body: htmlToMarkdown(comment.body),
                                 });
                             }
                         }
@@ -905,7 +946,7 @@ Example: jira_analyze_epic(issueKey="PROJ-100")`,
                     const description = rootIssue.fields.description;
                     if (description) {
                         lines.push("## Description");
-                        lines.push(truncateText(description, 500));
+                        lines.push(htmlToMarkdown(description));
                         lines.push("");
                     }
                     // Hierarchy breakdown
@@ -917,7 +958,7 @@ Example: jira_analyze_epic(issueKey="PROJ-100")`,
                         const completion = metrics.total > 0
                             ? Math.round((metrics.done / metrics.total) * 100)
                             : 0;
-                        lines.push(`| ${type} | ${metrics.total} | ${metrics.done} | ${metrics.inProgress} | ${metrics.todo} | ${completion}% |`);
+                        lines.push(`| ${sanitizeForTable(type)} | ${metrics.total} | ${metrics.done} | ${metrics.inProgress} | ${metrics.todo} | ${completion}% |`);
                     }
                     const totalCompletion = totals.total > 0
                         ? Math.round((totals.done / totals.total) * 100)
@@ -985,7 +1026,7 @@ Example: jira_analyze_epic(issueKey="PROJ-100")`,
                         lines.push("| Source | Relationship | Target | Project | Status |");
                         lines.push("|--------|--------------|--------|---------|--------|");
                         for (const dep of crossProjectDeps.slice(0, 20)) {
-                            lines.push(`| ${dep.source} | ${dep.relationship} | ${dep.target} | ${dep.project} | ${dep.status} |`);
+                            lines.push(`| ${dep.source} | ${sanitizeForTable(dep.relationship)} | ${dep.target} | ${dep.project} | ${sanitizeForTable(dep.status)} |`);
                         }
                         if (crossProjectDeps.length > 20) {
                             lines.push("");
@@ -1001,9 +1042,9 @@ Example: jira_analyze_epic(issueKey="PROJ-100")`,
                         const shownComments = recentComments.slice(0, 15);
                         for (const comment of shownComments) {
                             const dateStr = formatDisplayDateTime(comment.date);
-                            const body = comment.body.replace(/\n/g, " ").trim();
+                            // Body already converted via htmlToMarkdown during collection
                             lines.push(`- **${comment.issueKey}** @${comment.author} (${dateStr}):`);
-                            lines.push(`  "${body}"`);
+                            lines.push(`  "${comment.body}"`);
                         }
                         if (recentComments.length > 15) {
                             lines.push(`- *...and ${recentComments.length - 15} more comments*`);
@@ -1228,10 +1269,10 @@ Example: jira_epic_summary(issueKey="PROJ-100")`,
                     lines.push("| Key | Type | Summary | Status | Assignee |");
                     lines.push("|-----|------|---------|--------|----------|");
                     for (const issue of allIssues.slice(0, 50)) {
-                        const type = issue.fields.issuetype?.name || "?";
-                        const summary = truncateText(issue.fields.summary || "", 50);
-                        const status = issue.fields.status?.name || "?";
-                        const assignee = issue.fields.assignee?.displayName || "Unassigned";
+                        const type = sanitizeForTable(issue.fields.issuetype?.name) || "?";
+                        const summary = sanitizeForTable(truncateText(issue.fields.summary || "", 50));
+                        const status = sanitizeForTable(issue.fields.status?.name) || "?";
+                        const assignee = sanitizeForTable(issue.fields.assignee?.displayName) || "Unassigned";
                         lines.push(`| ${issue.key} | ${type} | ${summary} | ${status} | ${assignee} |`);
                     }
                     if (allIssues.length > 50) {
@@ -1246,7 +1287,7 @@ Example: jira_epic_summary(issueKey="PROJ-100")`,
                     lines.push("|------|-------|------|-------------|-------|------------|");
                     for (const [type, metrics] of byType) {
                         const completion = metrics.total > 0 ? Math.round((metrics.done / metrics.total) * 100) : 0;
-                        lines.push(`| ${type} | ${metrics.total} | ${metrics.done} | ${metrics.inProgress} | ${metrics.todo} | ${completion}% |`);
+                        lines.push(`| ${sanitizeForTable(type)} | ${metrics.total} | ${metrics.done} | ${metrics.inProgress} | ${metrics.todo} | ${completion}% |`);
                     }
                     lines.push(`| **TOTAL** | **${totalIssues}** | **${totalDone}** | **${totalInProgress}** | **${totalTodo}** | **${totalCompletion}%** |`);
                     lines.push("");
@@ -1257,7 +1298,7 @@ Example: jira_epic_summary(issueKey="PROJ-100")`,
                         lines.push("| Source | Relationship | Target | Project | Status |");
                         lines.push("|--------|--------------|--------|---------|--------|");
                         for (const dep of crossProjectDeps.slice(0, 20)) {
-                            lines.push(`| ${dep.source} | ${dep.relationship} | ${dep.target} | ${dep.project} | ${dep.status} |`);
+                            lines.push(`| ${dep.source} | ${sanitizeForTable(dep.relationship)} | ${dep.target} | ${dep.project} | ${sanitizeForTable(dep.status)} |`);
                         }
                         if (crossProjectDeps.length > 20) {
                             lines.push("");
@@ -1483,7 +1524,7 @@ Example: jira_analyze_sprint(sprintId=123)`,
                                     issueKey,
                                     author: comment.author.displayName,
                                     date: comment.created,
-                                    body: truncateText(comment.body, 200),
+                                    body: htmlToMarkdown(comment.body),
                                 });
                             }
                         }
@@ -1522,7 +1563,7 @@ Example: jira_analyze_sprint(sprintId=123)`,
                     lines.push("| Type | Total | Done | In Progress | To Do |");
                     lines.push("|------|-------|------|-------------|-------|");
                     for (const [type, metrics] of byType) {
-                        lines.push(`| ${type} | ${metrics.total} | ${metrics.done} | ${metrics.inProgress} | ${metrics.todo} |`);
+                        lines.push(`| ${sanitizeForTable(type)} | ${metrics.total} | ${metrics.done} | ${metrics.inProgress} | ${metrics.todo} |`);
                     }
                     lines.push("");
                     // Time metrics
@@ -1549,7 +1590,7 @@ Example: jira_analyze_sprint(sprintId=123)`,
                     // Sort by total issues descending
                     const sortedAssignees = Array.from(byAssignee.entries()).sort((a, b) => b[1].total - a[1].total);
                     for (const [assignee, metrics] of sortedAssignees.slice(0, 15)) {
-                        lines.push(`| ${assignee} | ${metrics.total} | ${metrics.done} | ${metrics.inProgress} |`);
+                        lines.push(`| ${sanitizeForTable(assignee)} | ${metrics.total} | ${metrics.done} | ${metrics.inProgress} |`);
                     }
                     if (sortedAssignees.length > 15) {
                         lines.push(`| *...and ${sortedAssignees.length - 15} more* | | | |`);
@@ -1561,7 +1602,7 @@ Example: jira_analyze_sprint(sprintId=123)`,
                         lines.push("");
                         lines.push(`⚠️ **${risks.length} issue${risks.length > 1 ? "s" : ""} at risk:**`);
                         for (const risk of risks.slice(0, 10)) {
-                            lines.push(`- **${risk.issueKey}**: ${risk.detail}`);
+                            lines.push(`- **${risk.issueKey}**: ${sanitizeForTable(risk.detail)}`);
                         }
                         if (risks.length > 10) {
                             lines.push(`- *...and ${risks.length - 10} more risks*`);
@@ -1580,8 +1621,8 @@ Example: jira_analyze_sprint(sprintId=123)`,
                         lines.push("");
                         for (const comment of recentComments.slice(0, 10)) {
                             const dateStr = formatDisplayDate(comment.date);
-                            const body = comment.body.replace(/\n/g, " ").trim();
-                            lines.push(`- **${comment.issueKey}** @${comment.author} (${dateStr}): "${body}"`);
+                            // Body already converted via htmlToMarkdown during collection
+                            lines.push(`- **${comment.issueKey}** @${comment.author} (${dateStr}): "${comment.body}"`);
                         }
                         if (recentComments.length > 10) {
                             lines.push(`- *...and ${recentComments.length - 10} more comments*`);
@@ -1592,7 +1633,7 @@ Example: jira_analyze_sprint(sprintId=123)`,
                     lines.push("---");
                     lines.push("## Summary");
                     lines.push("");
-                    lines.push(`Sprint "${sprint.name}" is **${completionPercent}% complete** with ${statusCounts.inProgress} issues in progress and ${statusCounts.todo} issues remaining.`);
+                    lines.push(`Sprint "${sanitizeForTable(sprint.name)}" is **${completionPercent}% complete** with ${statusCounts.inProgress} issues in progress and ${statusCounts.todo} issues remaining.`);
                     if (daysRemaining > 0) {
                         lines.push(`**${daysRemaining} days remaining** in the sprint.`);
                     }