@crypto512/jicon-mcp 2.3.0 → 2.3.19

package/dist/utils/jicon-help.js

@@ -11,7 +11,7 @@ const TOPICS = ["jql", "cql", "storage", "plantuml", "buffers", "analysis"];
 // Default workflow guide (shown when no topic specified)
 const WORKFLOW_GUIDE = `# Jicon Quick Reference
 
-TOOLS: jira(26) confluence(21) tempo(13) buffer(12) plantuml(3) url(2) date(1) help(1)
+TOOLS: jira, confluence, tempo, buffer, workload, plantuml, url, date, help, whoami
 
 ## Decision Tree - Which Topic?
 
@@ -30,6 +30,8 @@ TOOLS: jira(26) confluence(21) tempo(13) buffer(12) plantuml(3) url(2) date(1) h
 | Search Confluence | \`help(topic="cql")\` |
 | Search Jira | \`jira_get_issue_types()\` then \`help(topic="jql")\` |
 | Non-English Jira fields | \`jira_get_fields(search="epic")\` → use cf[ID] syntax |
+| **Find user for JQL query** | \`jira_search_users(query="name")\` → get username for assignee/reporter JQL |
+| **Issues worked on in period** | \`tempo_get_worklogs(workerKey, dateFrom, dateTo)\` ← NOT JQL created/updated |
 | Log/get time | \`tempo_get_user_info()\` first |
 | **Create table for Confluence** | \`buffer_transform(..., code="return toTable(issues,{columns:[...]})")\` → XHTML |
 | **Create table to show user** | \`buffer_transform(..., code="return toMarkdownTable(issues,{columns:[...]})")\` → Markdown |
@@ -130,7 +132,7 @@ const JQL_HELP = `# JQL Syntax Guide
 
 Before writing JQL with type/status names:
 1. Use \`jira_get_issue_types()\` to discover actual type names (e.g., "Epic" vs "Épopée")
-2. Use \`jira_get_fields()\` to discover field names (e.g., "Epic Link" vs "Lien d'épopée")
+2. Use \`jira_get_fields(search="epic")\` to discover field names (e.g., "Epic Link" vs "Lien d'épopée")
 3. Use \`cf[ID]\` syntax for language-independent field queries
 
 The examples below use English names. Replace with your instance's actual values.
@@ -156,27 +158,32 @@ The examples below use English names. Replace with your instance's actual values
 4. Recently updated issues (last 7 days):
    updated >= startOfDay(-7)
 
-5. Issues by assignee:
+5. Issues by assignee (current user):
    assignee = currentUser()
 
-6. Text search in summary/description:
+6. Issues by a specific person (find their username first):
+   jira_search_users(query="Fabien") → returns username (e.g., "fthuillier")
+   assignee = "fthuillier"
+
+7. Text search in summary/description:
    summary~"login" OR description~"login"
 
-7. Date range:
+8. Date range:
    created >= "2025-01-01" AND created <= "2025-01-31"
 
-8. Multiple projects:
+9. Multiple projects:
    project IN (PROJ1, PROJ2, PROJ3)
 
-9. Exclude resolved:
-   resolution = Unresolved
+10. Exclude resolved (language-independent):
+    statusCategory != Done
 
-10. Issues with specific label:
+11. Issues with specific label:
     labels = "urgent" AND status != Done
 
 ## Tips
 - Use jira_get_issue_types first to discover type names for your instance
 - Use jira_get_fields to discover field names in your language
+- Use jira_search_users to find a person's username for assignee/reporter queries
 - Date functions: startOfDay(), startOfWeek(), startOfMonth(), now()
 - Relative dates: startOfDay(-7) = 7 days ago
 - Always quote field values that contain spaces
@@ -212,7 +219,32 @@ The \`clauseNames\` array shows all valid JQL names for a field.
 ## Date Handling Tips
 - "Last week" in business context = previous Mon-Fri (e.g., Dec 8-12)
 - "Rolling 7 days" = use startOfDay(-7)
-- For exact date ranges, use explicit dates: updated >= "2025-12-08" AND updated <= "2025-12-12"`;
+- For exact date ranges, use explicit dates: updated >= "2025-12-08" AND updated <= "2025-12-12"
+
+## Language-Independent Best Practices
+
+**Always use these approaches for reliable JQL across all Jira instances:**
+- Use \`statusCategory != Done\` instead of \`resolution = Unresolved\`
+- Use \`cf[ID]\` syntax for custom fields instead of localized names
+- Tools like \`jira_list_epic_children\` automatically try multiple patterns
+
+## Troubleshooting Common JQL Errors
+
+### "Le champ 'X' n'existe pas" / "Field 'X' does not exist"
+**Cause**: Field name is localized or doesn't exist on this instance
+**Solution**:
+1. Run \`jira_get_fields(search="part_of_name")\` to find the field
+2. Use the \`clauseNames\` value or \`cf[ID]\` syntax
+
+### Query returns 0 results but issues exist
+**Cause**: Type name mismatch (e.g., searching for "Epic" when locale uses "Épopée")
+**Solution**:
+1. Run \`jira_get_issue_types()\` to see actual type names
+2. Use the exact name from the response
+
+### "resolution = Unresolved" not working in non-English instance
+**Cause**: "Unresolved" may not work consistently across all locales
+**Solution**: Use \`statusCategory != Done\` (works in any language)`;
 // CQL syntax guide
 const CQL_HELP = `# CQL Syntax Guide
 
@@ -233,6 +265,8 @@ CQL is largely language-independent:
 ## Critical Warnings
 WARNING: Do NOT use 'content~' or 'body~' - they're invalid! Use 'text~' instead.
 
+WARNING: Do NOT use 'lastmodifiedby' or 'lastmodifier' - they don't exist! Use 'contributor=' instead.
+
 WARNING: WRONG: text~("term1" OR "term2") - Cannot use OR inside the operator
 OK: (text~"term1" OR text~"term2") - Each term needs its own text~ operator
 
@@ -243,35 +277,51 @@ OK: (text~"term1" OR text~"term2") - Each term needs its own text~ operator
 2. Pages created by a person:
    type=page AND creator="username"
 
-3. Pages with specific label:
+3. Pages I created OR edited:
+   contributor=currentUser() ORDER BY lastmodified DESC
+
+4. Pages with specific label:
    type=page AND label="meeting-notes"
 
-4. Pages in space modified recently:
+5. Pages in space modified recently:
    space=DOCS AND lastmodified >= now("-30d") ORDER BY lastmodified DESC
 
-5. Text search in a space:
+6. Text search in a space:
    text~"API" AND space=DOCS AND type=page
 
-6. Date range:
+7. Date range:
    lastmodified >= "2025-01-01" AND lastmodified <= "2025-01-31"
 
-7. Multiple spaces:
+8. Multiple spaces:
    space IN (DOCS, PROJ, WIKI)
 
-8. Pages by title pattern:
+9. Pages by title pattern:
    type=page AND title~"Sprint Review" ORDER BY created DESC
 
-9. Find by creator name:
-   creator.fullname~"Alex Morgan"
+10. Find by creator name:
+    creator.fullname~"Alex Morgan"
 
-10. Pages created this week:
+11. Pages created this week:
     type=page AND created >= startOfWeek()
 
 ## Tips
 - Use space KEY (e.g., 'DOCS') not space name (e.g., 'Documentation')
 - Date functions: now(), startOfDay(), startOfWeek(), startOfMonth()
 - Relative dates: now("-7d") = 7 days ago
-- Results are always buffered - use buffer_get_items to read, buffer_grep to search`;
+- Results are always buffered - use buffer_get_items to read, buffer_grep to search
+
+## User Fields
+
+| Field | Meaning |
+|-------|---------|
+| creator | Original author only |
+| contributor | Created OR edited |
+
+## Invalid Fields
+
+These do NOT exist in CQL:
+- lastmodifiedby, lastmodifier → use contributor=
+- content~, body~ → use text~`;
 // Confluence storage format (XHTML syntax only)
 const STORAGE_FORMAT_HELP = `# Confluence Storage Format (XHTML)
 
@@ -688,152 +738,40 @@ buffer_edit(bufferId, old_string="foo", new_string="bar", replace_all=true)
 buffer_edit(bufferId, append=true, content="text to add at end")
 \`\`\`
 
-## JavaScript Sandbox (buffer_transform) - RECOMMENDED
+## JavaScript Sandbox (buffer_transform)
 
-Transform JSON buffers with JavaScript code in a secure sandbox. Write custom transformation logic!
-
-**Benefits:**
-- Full JavaScript expressiveness (filter, map, reduce, etc.)
-- Multiple input buffers in single transformation
-- Built-in helpers for common operations
-- XHTML table/list generation with auto-linking and styling
-
-**Schema Types:**
-All JSON buffers from API tools have a schemaType (e.g., "jira_issue", "tempo_worklog").
-Fields are flattened for easy access. Use \`buffer_get_schema(bufferId)\` to see available fields with samples.
+Transform JSON buffers with JavaScript code in a secure sandbox.
 
 **Basic workflow:**
 \`\`\`
-1. jira_search_issues(jql="...")
-   → { bufferId, schemaType: "jira_issue", fields: ["key","summary","status",...] }
-
-2. buffer_get_schema(bufferId)  # Optional: see all fields with samples
-   → { fields: { key: {..., sample: "PROJ-1"}, status: {..., sample: "Open"} } }
-
-3. buffer_transform(
-     inputs: { issues: bufferId },
-     code: \`
-       const open = issues.filter(i => i.status !== 'Done');
-       return toTable(open, {
-         title: 'Open Issues',
-         columns: [
-           { field: 'key', header: 'Issue', link: { type: 'jira' } },
-           { field: 'summary', header: 'Summary' },
-           { field: 'priority', header: 'Priority' }
-         ]
-       });
-     \`
-   )
-   → { bufferId: "buf_new", contentType: "xhtml" }
-
-4. Insert into Confluence page or use directly
-\`\`\`
-
-**Built-in helpers (available as globals in sandbox):**
-\`\`\`javascript
-// Aggregation
-groupBy(array, keyOrFn)    // → { key: items[] }
-sum(array, field?)         // → number
-avg(array, field?)         // → number
-min(array, field?)         // → value
-max(array, field?)         // → value
-count(array)               // → number
-unique(array, field?)      // → unique values[]
-
-// Object access
-get(obj, 'path.to.field')  // → value (dot notation)
-pick(obj, ['a', 'b'])      // → subset object
-omit(obj, ['a'])           // → object without keys
-
-// Date utilities
-parseDate(string)          // → timestamp (ms)
-formatDate(ts, fmt?)       // → string (fmt: 'date', 'time', 'datetime', 'iso')
-daysBetween(d1, d2)        // → number
-
-// Context (for link generation)
-JIRA_URL                   // → string | undefined
-CONFLUENCE_URL             // → string | undefined
+1. jira_search_issues(jql="...") → { bufferId }
+2. buffer_get_schema(bufferId)  # See available fields with samples
+3. buffer_transform(inputs: { issues: bufferId }, code: "return toTable(...)")
+4. confluence_draft_create(bufferId) or display to user
 \`\`\`
 
-**OUTPUT FORMAT - CHOOSE BASED ON DESTINATION:**
+**OUTPUT FORMAT - CHOOSE BY DESTINATION:**
 
-| Destination | Formatters | Result | Next Step |
-|-------------|-----------|--------|-----------|
-| **Confluence page** | toTable(), toList() | XHTML buffer | confluence_draft_create(bufferId) |
-| **Display to user** | toMarkdownTable(), toMarkdownList() | Markdown buffer | buffer_get_items(bufferId, keys=['content']) |
+| Destination | Formatters | Result |
+|-------------|-----------|--------|
+| **Confluence page** | toTable(), toList() | XHTML |
+| **Display to user** | toMarkdownTable(), toMarkdownList() | Markdown |
 
-⚠️ **Common mistake**: Using toTable() when you want to display results to user. Use toMarkdownTable() instead!
+⚠️ **Common mistake**: Using toTable() when you want to display to user. Use toMarkdownTable() instead!
 
-**toTable() / toMarkdownTable() - Table Generator:**
-\`\`\`javascript
-// For Confluence page:
-toTable(array, config)
-
-// For user display (same config!):
-toMarkdownTable(array, config)
-
-// Config options:
-{
-  title: 'Table Title',         // Optional title above table
-  showRowNumbers: true,         // Add # column
-  tableClass: 'confluenceTable',// CSS class (XHTML only)
-  columns: [
-    { field: 'key', header: 'Issue', link: { type: 'jira' } },
-    { field: 'summary', header: 'Summary', width: '40%' },
-    { field: 'priority', header: 'Priority', align: 'center' }  // Flat field!
-  ],
-  format: [  // Conditional styling
-    {
-      condition: { field: 'priority', operator: 'eq', value: 'Blocker' },
-      style: { color: '#d04437', bold: true, icon: '🔴' },
-      fields: ['priority']  // Apply to specific fields (or omit for row)
-    }
-  ]
-}
-\`\`\`
+**Built-in helpers:** groupBy, sum, avg, min, max, count, unique, get, pick, omit, parseDate, formatDate, daysBetween, JIRA_URL, CONFLUENCE_URL
 
-**toList() / toMarkdownList() - List Generator:**
-\`\`\`javascript
-// For Confluence page:
-toList(array, config)
-
-// For user display (same config!):
-toMarkdownList(array, config)
-
-// Config options:
-{
-  title: 'List Title',
-  style: 'bullet',  // 'bullet', 'numbered', 'none' (or 'task' for Markdown)
-  template: '{{key}}: {{summary}} ({{assignee.displayName}})'
-}
-\`\`\`
-
-**Link types:** jira (auto-links to issue), confluence (to page ID), custom (template with {{field}})
-
-**Format condition operators:** eq, ne, gt, lt, gte, lte, contains, startsWith, endsWith, in, notIn, exists, notExists, regex, empty, notEmpty
-
-**Example - Statistics by assignee:**
+**Example - Table for user display:**
 \`\`\`javascript
 buffer_transform(
   inputs: { issues: bufferId },
   code: \`
-    const open = issues.filter(i => i.status.name !== 'Done');
-    const byAssignee = groupBy(open, 'assignee.displayName');
-
-    const stats = Object.entries(byAssignee).map(([name, items]) => ({
-      assignee: name,
-      total: items.length,
-      issues: items.map(i => i.key).join(', ')
-    }));
-
-    stats.sort((a, b) => b.total - a.total);
-
-    return toTable(stats, {
-      title: 'Work Distribution',
+    const open = issues.filter(i => i.status !== 'Done');
+    return toMarkdownTable(open, {
       columns: [
-        { field: 'assignee', header: 'Assignee' },
-        { field: 'total', header: 'Open Issues', align: 'right' },
-        { field: 'issues', header: 'Issue Keys' }
+        { field: 'key', header: 'Issue', link: { type: 'jira' } },
+        { field: 'summary', header: 'Summary' },
+        { field: 'assignee', header: 'Assignee' }
       ]
     });
   \`
@@ -841,16 +779,16 @@ buffer_transform(
 \`\`\`
 
 **When to use buffer_transform:**
-- Generating tables/lists for Confluence → use toTable(), toList()
-- Generating tables/lists to show user → use toMarkdownTable(), toMarkdownList()
+- Generating tables/lists for Confluence or user display
 - Custom filtering and transformation logic
 - Aggregating statistics across multiple buffers
-- Complex data manipulation (joins, pivots, etc.)
 
 **When NOT to use buffer_transform:**
 - When you need LLM judgment on each item (use buffer_get_items)
 - When decisions require analyzing content semantically
 
+**For formatter details:** See TOOL_LIST.md or tool description for toTable/toList config options.
+
 ## Decision Forks (Choose Your Path)
 
 After jira_search_issues/tempo_get_worklogs returns a bufferId, you have OPTIONS:
@@ -958,188 +896,18 @@ These **intelligent entry points** return pre-processed data **directly to the L
 - **Regular tools** → Buffer data → Use buffer_transform for transformation → Token-efficient
 - **Analysis tools** → Return markdown directly to LLM → Enable AI insight and synthesis
 
-## When to Use Analysis Tools
-
-| Task | Tool | Example Query |
-|------|------|---------------|
-| What happened on project X? | \`jira_get_activity_digest\` | "What happened on PROJ this week?" |
-| Any blockers in discussions? | \`jira_get_recent_comments\` | "Are there blockers mentioned in recent comments?" |
-| Track field changes | \`jira_get_changelog\` | "What issues had priority escalations?" |
-| Deep Epic analysis | \`jira_analyze_epic\` | "Analyze Epic PROJ-100 for risks and progress" |
-| Sprint progress & risks | \`jira_analyze_sprint\` | "How is Sprint 42 progressing?" |
-| Quick Epic status | \`jira_epic_summary\` | "Quick status of Epic PROJ-100" |
-| List Epic children | \`jira_list_epic_children\` | "List open Stories in PROJ-100" |
-| Top issues by workload | \`tempo_get_top_worklogs\` | "Which issues had most work last week?" |
-
-## Tool Details
-
-### jira_get_activity_digest
-Fetches comments, status/priority/assignee changes across issues.
-
-\`\`\`
-jira_get_activity_digest(
-  projectKey="ACME",      // or jql="..." or issueKeys=[...]
-  since="7d",             // "1d", "7d", "30d", or ISO date
-  includeComments=true,
-  includeStatusChanges=true,
-  includePriorityChanges=true,
-  includeAssigneeChanges=true
-)
-\`\`\`
-
-**Returns**: Markdown with activities grouped by issue + summary statistics:
-- Issues with activity count
-- Status changes (with "to Done" breakdown)
-- Priority escalations
-- New comments count
-
-### jira_get_recent_comments
-Aggregates comments across multiple issues for discussion analysis.
-
-\`\`\`
-jira_get_recent_comments(
-  projectKey="ACME",
-  since="7d",
-  authorKey="john",       // optional: filter by author
-  maxComments=30
-)
-\`\`\`
-
-**Returns**: Markdown with comments grouped by issue + context (status).
-
-### jira_get_changelog
-Tracks field changes across issues.
-
-\`\`\`
-jira_get_changelog(
-  projectKey="ACME",
-  since="7d",
-  fields=["status", "priority", "assignee", "resolution"],
-  maxChanges=50
-)
-\`\`\`
-
-**Returns**: Markdown with changes grouped by issue + field breakdown.
-
-### jira_analyze_epic
-Comprehensive Epic/Feature analysis for deep insights.
-
-\`\`\`
-jira_analyze_epic(
-  issueKey="PROJ-100",
-  includeComments=true,
-  commentDays=14,
-  maxComments=5
-)
-\`\`\`
-
-**Returns**: Comprehensive markdown analysis including:
-- **Hierarchy**: Epic → Stories → Subtasks with completion %
-- **Time Metrics**: Spent vs estimated, burn rate, overrun warnings
-- **Progress Indicators**: Velocity, in-flight issues
-- **Architecture Context**: Components, labels
-- **Linked Resources**: Confluence pages, related issues
-- **Recent Discussions**: Technical comments for context
-
-**Example output snippet:**
-\`\`\`markdown
-## Issue Hierarchy
-| Type | Total | Done | In Progress | To Do | Completion |
-|------|-------|------|-------------|-------|------------|
-| Story | 5 | 3 | 1 | 1 | 60% |
-| Sub-task | 12 | 8 | 2 | 2 | 67% |
-
-## Time Metrics
-- Time Spent: 2w 3d
-- Original Estimate: 3w
-- Burn Rate: 77% of estimate consumed
-- ⚠️ Overrun: 2d over estimate
-
-## Analysis Summary
-This Epic contains **17 issues** with **65% completion**.
-⚠️ **77% of time used but only 65% complete** - at risk of overrun.
-\`\`\`
-
-### jira_analyze_sprint
-Comprehensive Sprint analysis for progress, risks, and team distribution.
-
-\`\`\`
-jira_analyze_sprint(
-  sprintId=123,           // from jira_get_sprints(boardId)
-  includeComments=true,
-  commentDays=7,
-  includeRisks=true
-)
-\`\`\`
-
-**How to find sprintId**: Call \`jira_get_sprints(boardId)\` first. BoardId can be found in Jira URLs like \`/secure/RapidBoard.jspa?rapidView=123\`.
-
-**Returns**: Comprehensive markdown analysis including:
-- **Sprint Metadata**: Dates, duration, days remaining
-- **Progress**: Completion %, status breakdown (Done/In Progress/To Do)
-- **Issue Breakdown**: By type and status
-- **Time Metrics**: Estimated vs spent vs remaining, burn rate
-- **Team Distribution**: Who's working on what
-- **Risk Indicators**: Stale issues, blocked, high-priority unstarted
-- **Recent Discussions**: Comments from team
-
-**Example output snippet:**
-\`\`\`markdown
-# Sprint Analysis: Sprint 42
-
-**State**: Active
-**Period**: Jan 20 - Feb 3 (14 days)
-**Progress**: Day 10 of 14 (4 days remaining)
+## Tool Quick Reference
 
-## Sprint Progress
-**Completion**: 65% (13 of 20 issues done)
-
-## Risk Indicators
-⚠️ **3 issues at risk:**
-- PROJ-456: In Progress for 5 days without update
-- PROJ-789: High priority, still To Do
-\`\`\`
-
-### jira_epic_summary
-Lightweight Epic status - no time metrics, no comments, no Confluence links.
-
-\`\`\`
-jira_epic_summary(
-  issueKey="PROJ-100",
-  includeLinks=true,      // cross-project dependencies
-  maxDepth=3              // hierarchy depth
-)
-\`\`\`
-
-**Returns**: Quick markdown with hierarchy list, status breakdown, cross-project dependencies.
-
-### jira_list_epic_children
-List Epic children without needing JQL. Auto-detects Epic Link and Parent Link fields.
-
-\`\`\`
-jira_list_epic_children(
-  parentKey="PROJ-100",
-  type="Story",           // optional: filter by type
-  status="open",          // "open", "closed", "all"
-  recursive=false         // true for nested children
-)
-\`\`\`
-
-**Returns**: Buffered results (same format as jira_search_issues).
-
-### tempo_get_top_worklogs
-Top issues or users by workload. Returns directly to LLM.
-
-\`\`\`
-tempo_get_top_worklogs(
-  since="last_week",      // date expression
-  projectKey="PROJ",      // optional filter
-  groupBy="issue",        // "issue" or "user"
-  limit=10
-)
-\`\`\`
-
-**Returns**: Markdown table with ranked results + totals.
+| Tool | Purpose | Best For |
+|------|---------|----------|
+| \`jira_get_activity_digest\` | Recent activity across issues | "What happened on PROJ this week?" |
+| \`jira_get_recent_comments\` | Discussion analysis | "Any blockers in recent discussions?" |
+| \`jira_get_changelog\` | Track field changes | "What issues had priority escalations?" |
+| \`jira_analyze_epic\` | Deep Epic analysis | "Analyze Epic PROJ-100 for risks" |
+| \`jira_analyze_sprint\` | Sprint progress & risks | "How is Sprint 42 progressing?" |
+| \`jira_epic_summary\` | Quick Epic status | "Quick status of Epic PROJ-100" |
+| \`jira_list_epic_children\` | List Epic children | "List open Stories in PROJ-100" |
+| \`tempo_get_top_worklogs\` | Top issues by workload | "Which issues had most work?" |
 
 ## Scoping Parameters
 
@@ -1163,6 +931,27 @@ Use \`date_resolve(expression)\` to preview date ranges:
 date_resolve("this_week") → { dateFrom: "2025-01-27", dateTo: "2025-01-31", businessDays: 5 }
 \`\`\`
 
+## Choosing the Right Tool
+
+### Activity & Discussions
+- **What happened?** → \`jira_get_activity_digest(projectKey, since="7d")\`
+- **What are people saying?** → \`jira_get_recent_comments(projectKey, since="7d")\`
+- **What changed?** → \`jira_get_changelog(projectKey, fields=["status","priority"])\`
+
+### Epic Analysis
+- **Full Epic analysis** (time, comments, links) → \`jira_analyze_epic(issueKey)\`
+- **Quick Epic status** (no time metrics) → \`jira_epic_summary(issueKey)\`
+- **List Epic children** (buffered for transform) → \`jira_list_epic_children(parentKey)\`
+
+### Sprint Analysis
+- **Sprint health check** → \`jira_analyze_sprint(sprintId)\`
+  - Find sprintId: \`jira_get_sprints(boardId)\`
+  - Find boardId: \`jira_list_boards()\` or from URL \`/rapidView=123\`
+
+### Time Tracking
+- **Top issues by workload** → \`tempo_get_top_worklogs(since, groupBy="issue")\`
+- **Top contributors** → \`tempo_get_top_worklogs(since, groupBy="user")\`
+
 ## vs Buffer Transform
 
 | Need | Use |
@@ -1187,7 +976,8 @@ date_resolve("this_week") → { dateFrom: "2025-01-27", dateTo: "2025-01-31", bu
 - Use \`date_resolve\` to understand date ranges before querying
 - Start with smaller \`maxActivities\`/\`maxComments\` for faster responses
 - Combine with \`jira_search_issues\` to narrow scope first if needed
-- Analysis tools return markdown directly - no buffering needed`;
+- Analysis tools return markdown directly - no buffering needed
+- For parameter details, see tool descriptions or TOOL_LIST.md`;
 // Topic content map
 const TOPIC_CONTENT = {
     jql: JQL_HELP,

package/dist/utils/jicon-help.js.map

@@ -1 +1 @@
-{"version":3,"file":"jicon-help.js","sourceRoot":"","sources":["../../src/utils/jicon-help.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"jicon-help.js","sourceRoot":"","sources":["../../src/utils/jicon-help.ts"],"names":[],"mappings":"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"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Logger utility with timestamp and log level support
+ *
+ * All MCP server logs go to stderr (stdout is reserved for MCP protocol)
+ *
+ * Log levels (JICON_LOG_LEVEL):
+ * - error: Only errors
+ * - warn: Errors and warnings
+ * - info: Errors, warnings, and info messages (default)
+ * - debug: All messages including debug output
+ */
+/**
+ * Log a message with timestamp prefix (info level)
+ * @param args - Arguments to log (same as console.error)
+ */
+export declare function log(...args: unknown[]): void;
+/**
+ * Log a debug message (only when JICON_LOG_LEVEL=debug)
+ * @param args - Arguments to log
+ */
+export declare function debug(...args: unknown[]): void;
+/**
+ * Log an info message
+ * @param message - Message to log
+ */
+export declare function info(message: string): void;
+/**
+ * Log a warning message
+ * @param message - Warning message
+ */
+export declare function warn(message: string): void;
+/**
+ * Log an error message
+ * @param message - Error message
+ * @param err - Optional error object
+ */
+export declare function error(message: string, err?: unknown): void;
+/**
+ * Check if debug logging is enabled
+ * Use this to avoid expensive string formatting when debug is disabled
+ */
+export declare function isDebugEnabled(): boolean;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAyCH;;;GAGG;AACH,wBAAgB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAI5C;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAI9C;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAI1C;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAI1C;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,CAQ1D;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAExC"}