@crypto512/jicon-mcp 2.2.1 → 2.3.19

package/dist/jira/tools.js

@@ -1,23 +1,31 @@
 /**
  * Jira MCP Tools
+ *
+ * All tool handlers use session-scoped clients and buffers via getSessionXxxClient()
+ * and getSessionBuffer() functions which provide per-session isolation.
  */
 import { z } from "zod";
-import { formatSuccess, formatSuccessJson, formatError, isApiError, formatConflictError } from "../utils/response-formatter.js";
-import { contentBuffer } from "../utils/content-buffer.js";
-import { formatIssueMetadata } from "./formatters.js";
+import { formatSuccess, formatSuccessJson, formatError, isApiError, formatConflictError, getMaxApiResults } from "../utils/response-formatter.js";
+import { getSessionBuffer, getSessionJiraClient } from "../session/context.js";
+import { formatIssueMetadata, formatCommentMetadata, formatProjectMetadata, formatBoardMetadata, formatSprintMetadata, formatWorklogMetadata, } from "./formatters.js";
 import { formatTimeSpent } from "../utils/time-formatter.js";
 /**
- * Create Jira tools with a client getter function
+ * Schema that accepts either a comma-separated string or an array of strings.
+ * Examples: "changelog,renderedFields" or ["changelog", "renderedFields"]
+ */
+const stringOrArray = z.preprocess((val) => typeof val === "string" ? val.split(",").map(s => s.trim()).filter(Boolean) : val, z.array(z.string()));
+/**
+ * Create Jira tools using session-scoped clients
  *
- * @param getClient - Function that returns the appropriate JiraClient for the current request.
- *                    May return null if Jira is not configured.
+ * Tools automatically use the JiraClient from the current session context,
+ * which provides per-session caching and credential isolation.
  */
-export function createJiraTools(getClient) {
+export function createJiraTools() {
     /**
      * Helper to get client and throw if not available
      */
     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.");
         }
@@ -25,40 +33,56 @@ export function createJiraTools(getClient) {
     };
     return {
         jira_search_issues: {
-            description: `Search Jira issues using JQL. Auto-fetches all results (up to 5000).
+            description: `Search Jira issues using JQL. Auto-fetches all matching results.
 
 Entry point for any Jira data analysis, reporting, or bulk workflow.
 
 REQUIRES: Valid JQL query (see help(topic="jql") for syntax)
-
-RESPONSE FIELDS:
-- returnedItems: Items available in buffer - USE THIS for actual count
-- jiraTotalMatching: Total Jira found (may exceed returnedItems if > 5000)
-- apiLimit: Max items per search (5000)
-- note: Explanation when results are truncated
-
-NEXT: buffer_pipeline (for tables/reports), buffer_get_items (for AI analysis)
-
-Example: jira_search_issues(jql="project=PROJ AND status='Open' ORDER BY priority DESC")`,
+TIP: Issue types are LOCALIZED (e.g., "Épopée" not "Epic", "Bogue" not "Bug").
+     Use jira_get_issue_types() first if unsure.
+TIP: If you know a person's name but not their username, call jira_search_users(query="name") first.
+
+TIME TRACKING: The "timespent" field is often NULL (time not logged directly on issue).
+For accurate time data, use jira_get_total_worklogs(issueKey) which recursively sums
+worklogs from the issue and all children. For bulk time reports, use tempo_get_worklogs.
+DATE RANGES: JQL created/updated filters find issues CREATED/UPDATED in a period.
+To find issues a user WORKED ON during a period (by logged time), use
+tempo_get_worklogs(workerKey, dateFrom, dateTo) instead — it returns all worklogs
+in the date range regardless of when issues were created.
+
+RESPONSE: Returns buffer with flat fields (status, assignee, priority - not nested).
+NEXT: buffer_transform for tables, buffer_get_items for analysis.
+
+Example: jira_search_issues(jql="project=PROJ AND statusCategory != Done")`,
             inputSchema: z.object({
                 jql: z.string().describe("JQL query string"),
-                fields: z.array(z.string()).optional().describe("Specific fields to return"),
+                fields: stringOrArray.optional().describe("Specific fields to return (string or array)"),
             }),
             handler: async (args) => {
                 try {
-                    const result = await requireClient().searchIssuesAll(args.jql, args.fields, 5000);
-                    // Use JSON buffer for structured access to issues
-                    const issues = result.issues || [];
-                    const metadata = {
+                    const result = await requireClient().searchIssuesAll(args.jql, args.fields, getMaxApiResults());
+                    // Flatten issues to match jira_issue schema
+                    const issues = (result.issues || []).map(formatIssueMetadata);
+                    return formatSuccessJson(issues, {
                         resourceType: "jira_search",
                         title: `JQL: ${args.jql.substring(0, 100)}${args.jql.length > 100 ? "..." : ""}`,
+                        schemaType: "jira_issue",
                         jql: args.jql,
                         totalIssues: result.total,
                         maxResults: result.maxResults,
-                    };
-                    return formatSuccessJson(issues, metadata);
+                    });
                 }
                 catch (error) {
+                    // Add JQL help hint for search errors
+                    if (isApiError(error) && (error.statusCode === 400 || error.message?.toLowerCase().includes('jql'))) {
+                        return formatError({
+                            ...error,
+                            details: {
+                                ...(error.details || {}),
+                                tip: 'Call help(topic="jql") for JQL syntax and localization guide',
+                            },
+                        });
+                    }
                     return formatError(isApiError(error) ? error : new Error(String(error)));
                 }
             },
@@ -67,15 +91,19 @@ Example: jira_search_issues(jql="project=PROJ AND status='Open' ORDER BY priorit
             description: `Get detailed information about a specific Jira issue.
 
 Use for viewing issue details, checking status before update, or getting comments.
+For MULTIPLE issues in a single buffer, use jira_get_issues instead.
 
 REQUIRES: Issue key (e.g., "PROJ-123")
 RETURNS: bufferId with issue data including fields, comments, attachments
 NEXT: jira_update_issue (to modify), jira_transition_issue (to change status), jira_add_comment
 
+TIME TRACKING: The "timespent" field is often NULL. For accurate time data,
+use jira_get_issue_worklogs or jira_get_total_worklogs instead.
+
 Example: jira_get_issue(issueKey="PROJ-123")`,
             inputSchema: z.object({
                 issueKey: z.string().describe('Issue key (e.g., "PROJ-123")'),
-                fields: z.array(z.string()).optional().describe("Specific fields to return"),
+                fields: stringOrArray.optional().describe("Specific fields to return (string or array)"),
                 expand: z
                     .array(z.string())
                     .optional()
@@ -87,15 +115,64 @@ Example: jira_get_issue(issueKey="PROJ-123")`,
                     // Handle case where fields might be missing or undefined
                     const summary = result?.fields?.summary || args.issueKey;
                     const issueKey = result?.key || args.issueKey;
-                    return formatSuccessJson({
-                        ...formatIssueMetadata(result),
-                        data: result,
-                    }, {
+                    const issueMetadata = formatIssueMetadata(result);
+                    const metadata = {
                         resourceType: "jira_issue",
+                        schemaType: "jira_issue",
                         title: `${issueKey}: ${summary}`,
                         resourceId: issueKey,
                         projectKey: issueKey.split("-")[0],
                         issueId: result?.id,
+                    };
+                    // Check if time fields were requested but are null - add guidance
+                    const timeFields = ["timespent", "timeoriginalestimate", "aggregatetimespent"];
+                    const requestedTimeFields = args.fields?.filter(f => timeFields.includes(f.toLowerCase())) || [];
+                    if (requestedTimeFields.length > 0) {
+                        const hasAnyTimeData = requestedTimeFields.some(f => issueMetadata[f] != null && issueMetadata[f] !== 0);
+                        if (!hasAnyTimeData) {
+                            metadata.timeTrackingHint = `Time fields are null for ${issueKey}. Use jira_get_issue_worklogs("${issueKey}") or jira_get_total_worklogs("${issueKey}") for accurate time data.`;
+                        }
+                    }
+                    return formatSuccessJson({
+                        ...issueMetadata,
+                        data: result,
+                    }, metadata);
+                }
+                catch (error) {
+                    return formatError(isApiError(error) ? error : new Error(String(error)));
+                }
+            },
+        },
+        jira_get_issues: {
+            description: `Get multiple Jira issues at once in a single buffer.
+
+Batch alternative to calling jira_get_issue multiple times. Returns a flat array
+with the same schema as jira_search_issues (jira_issue), ready for buffer_transform.
+
+REQUIRES: issueKeys (single key or array of keys)
+RETURNS: bufferId with flat issues array (same format as jira_search_issues)
+NEXT: buffer_transform (for tables/reports), buffer_get_items (for analysis)
+
+Example: jira_get_issues(issueKeys="PROJ-123")
+Example: jira_get_issues(issueKeys=["PROJ-123","PROJ-456","PROJ-789"])`,
+            inputSchema: z.object({
+                issueKeys: stringOrArray.describe('Issue key(s) - single key or array (e.g., "PROJ-123" or ["PROJ-123","PROJ-456"])'),
+                fields: stringOrArray.optional().describe("Specific fields to return (string or array)"),
+            }),
+            handler: async (args) => {
+                try {
+                    const keys = args.issueKeys;
+                    if (keys.length === 0) {
+                        return formatError(new Error("issueKeys must contain at least one key"));
+                    }
+                    const jql = `key in (${keys.join(",")})`;
+                    const result = await requireClient().searchIssuesAll(jql, args.fields, keys.length);
+                    const issues = (result.issues || []).map(formatIssueMetadata);
+                    return formatSuccessJson(issues, {
+                        resourceType: "jira_issues",
+                        title: keys.length === 1 ? keys[0] : `${keys.length} issues`,
+                        schemaType: "jira_issue",
+                        issueKeys: keys,
                     });
                 }
                 catch (error) {
@@ -166,7 +243,7 @@ Example: jira_update_issue(issueKey="PROJ-123", fields={summary: "New title", pr
                 try {
                     await requireClient().updateIssue(args.issueKey, args.fields, args.notifyUsers);
                     // Invalidate any cached buffers for this issue to prevent stale data
-                    contentBuffer.invalidateByMetadata({
+                    getSessionBuffer().invalidateByMetadata({
                         resourceType: "jira_issue",
                         resourceId: args.issueKey,
                     });
@@ -183,7 +260,7 @@ Example: jira_update_issue(issueKey="PROJ-123", fields={summary: "New title", pr
                             try {
                                 await requireClient().getIssue(args.issueKey);
                                 await requireClient().updateIssue(args.issueKey, args.fields, args.notifyUsers);
-                                contentBuffer.invalidateByMetadata({
+                                getSessionBuffer().invalidateByMetadata({
                                     resourceType: "jira_issue",
                                     resourceId: args.issueKey,
                                 });
@@ -237,7 +314,7 @@ Example: jira_transition_issue(issueKey="PROJ-123", transitionName="Done", comme
                 try {
                     await requireClient().transitionIssue(args.issueKey, args.transitionName, args.comment, args.fields);
                     // Invalidate any cached buffers for this issue
-                    contentBuffer.invalidateByMetadata({
+                    getSessionBuffer().invalidateByMetadata({
                         resourceType: "jira_issue",
                         resourceId: args.issueKey,
                     });
@@ -276,7 +353,7 @@ Example: jira_add_comment(issueKey="PROJ-123", comment="Analysis complete. Ready
                 try {
                     const result = await requireClient().addComment(args.issueKey, args.comment, args.visibility);
                     // Invalidate any cached buffers for this issue (comments are part of issue data)
-                    contentBuffer.invalidateByMetadata({
+                    getSessionBuffer().invalidateByMetadata({
                         resourceType: "jira_issue",
                         resourceId: args.issueKey,
                     });
@@ -307,8 +384,11 @@ Example: jira_get_issue_comments(issueKey="PROJ-123")`,
             handler: async (args) => {
                 try {
                     const result = await requireClient().getComments(args.issueKey, args.orderBy);
-                    return formatSuccessJson(result, {
+                    // Flatten comments to match jira_comment schema
+                    const comments = (result.comments || result || []).map((c) => formatCommentMetadata(c));
+                    return formatSuccessJson(comments, {
                         resourceType: "jira_comments",
+                        schemaType: "jira_comment",
                         title: `${args.issueKey} comments`,
                         issueKey: args.issueKey,
                     });
@@ -330,13 +410,16 @@ NEXT: jira_get_project (for details), jira_search_issues (to query project)
 Example: jira_list_projects()`,
             inputSchema: z.object({
                 recent: z.boolean().optional().describe("Only return recent projects"),
-                expand: z.array(z.string()).optional().describe("Additional data to expand"),
+                expand: stringOrArray.optional().describe("Additional data to expand (string or array)"),
             }),
             handler: async (args) => {
                 try {
                     const result = await requireClient().listProjects(args.recent, args.expand);
-                    return formatSuccessJson(result, {
+                    // Flatten projects to match jira_project schema
+                    const projects = (result || []).map(formatProjectMetadata);
+                    return formatSuccessJson(projects, {
                         resourceType: "jira_projects",
+                        schemaType: "jira_project",
                         title: args.recent ? "Recent Projects" : "All Projects",
                     });
                 }
@@ -357,13 +440,18 @@ NEXT: jira_search_issues (to query), jira_create_issue (to create in project)
 Example: jira_get_project(projectKey="PROJ")`,
             inputSchema: z.object({
                 projectKey: z.string().describe("Project key"),
-                expand: z.array(z.string()).optional().describe("Additional data to expand"),
+                expand: stringOrArray.optional().describe("Additional data to expand (string or array)"),
             }),
             handler: async (args) => {
                 try {
                     const result = await requireClient().getProject(args.projectKey, args.expand);
-                    return formatSuccessJson(result, {
+                    // Flatten project to match jira_project schema, keep raw data for extra fields
+                    return formatSuccessJson({
+                        ...formatProjectMetadata(result),
+                        data: result,
+                    }, {
                         resourceType: "jira_project",
+                        schemaType: "jira_project",
                         title: result.name || args.projectKey,
                         projectKey: args.projectKey,
                     });
@@ -405,26 +493,24 @@ Example workflow:
             },
         },
         jira_get_fields: {
-            description: `Get all available Jira fields (system and custom).
+            description: `Get Jira fields (system and custom). Requires a search term or "all".
 
 Use this to discover:
 - Field names in user's language (e.g., "Epic Link" vs "Lien d'épopée")
 - Custom field IDs for JQL queries (e.g., cf[10014])
 - Field schema types for identification
 
-RETURNS: List of fields with id, name, clauseNames, and schema
+RETURNS: List of fields with id, name, clauseNames, and schemaType
 
 Example workflow for Epic Link queries in any language:
-1. Call jira_get_fields()
-2. Find field with schema.custom = "com.pyxis.greenhopper.jira:gh-epic-link"
-3. Use either the localized name or cf[ID] syntax in JQL:
-   - French: "Lien d'épopée" = PROJ-123
-   - Language-independent: cf[10014] = PROJ-123`,
+1. Call jira_get_fields(search="epic") — searches name, id, clauseNames, AND schemaType
+2. Find field with schemaType "com.pyxis.greenhopper.jira:gh-epic-link"
+3. Use cf[ID] from clauseNames in JQL: cf[10014] IS EMPTY`,
             inputSchema: z.object({
+                search: z.string()
+                    .describe('Required. "all" to return every field, or a search term to filter by name, id, clauseNames, or schemaType (case-insensitive). Example: "epic", "priority", "all"'),
                 filter: z.enum(["all", "custom", "system", "navigable"]).optional()
-                    .describe("Filter fields: all (default), custom, system, or navigable"),
-                search: z.string().optional()
-                    .describe("Search in field name or id (case-insensitive)"),
+                    .describe("Filter by category: all (default), custom, system, or navigable"),
             }),
             handler: async (args) => {
                 try {
@@ -439,12 +525,16 @@ Example workflow for Epic Link queries in any language:
                     else if (args.filter === "navigable") {
                         fields = fields.filter(f => f.navigable);
                     }
-                    // Apply search
-                    if (args.search) {
+                    // Apply search (skip if "all")
+                    if (args.search && args.search.toLowerCase() !== "all") {
                         const searchLower = args.search.toLowerCase();
-                        fields = fields.filter(f => f.id.toLowerCase().includes(searchLower) ||
-                            f.name.toLowerCase().includes(searchLower) ||
-                            f.clauseNames?.some(c => c.toLowerCase().includes(searchLower)));
+                        fields = fields.filter(f => {
+                            const schema = (f.schema?.custom || f.schema?.system || f.schema?.type || "").toLowerCase();
+                            return f.id.toLowerCase().includes(searchLower) ||
+                                f.name.toLowerCase().includes(searchLower) ||
+                                f.clauseNames?.some(c => c.toLowerCase().includes(searchLower)) ||
+                                schema.includes(searchLower);
+                        });
                     }
                     // Format for readability
                     const formatted = fields.map(f => ({
@@ -464,6 +554,38 @@ Example workflow for Epic Link queries in any language:
                 }
             },
         },
+        jira_search_users: {
+            description: `Search for Jira users by name, username, or email.
+
+Use this BEFORE JQL queries when you need a person's username but only know their name.
+Returns matching users with username/key for use in JQL (assignee, reporter, etc.).
+
+REQUIRES: query (name to search for)
+RETURNS: List of matching users with key, name, displayName, emailAddress
+
+Example workflow:
+1. jira_search_users(query="Fabien") → finds users matching "Fabien"
+2. Use username in JQL: assignee = "fthuillier"
+
+Example: jira_search_users(query="Fabien")`,
+            inputSchema: z.object({
+                query: z.string().describe("Search text (display name, username, or email)"),
+                maxResults: z.number().optional().describe("Maximum results (default: 20)"),
+            }),
+            handler: async (args) => {
+                try {
+                    const users = await requireClient().searchUsers(args.query, args.maxResults);
+                    return formatSuccess({
+                        count: users.length,
+                        query: args.query,
+                        users,
+                    });
+                }
+                catch (error) {
+                    return formatError(isApiError(error) ? error : new Error(String(error)));
+                }
+            },
+        },
         jira_get_transitions: {
             description: `Get available transitions for an issue.
 
@@ -516,6 +638,38 @@ Example: jira_link_issues(issueKey="PROJ-123", linkedIssueKey="PROJ-456", linkTy
                 }
             },
         },
+        jira_list_boards: {
+            description: `List all Jira Agile boards. Entry point for discovering boards.
+
+View all Scrum and Kanban boards with optional filtering by project, type, or name.
+
+RETURNS: bufferId with board list (id, name, type, projectKey)
+NEXT: jira_get_sprints (for Scrum boards), jira_search_issues (with board filter)
+
+Example: jira_list_boards()
+Example: jira_list_boards(projectKeyOrId="PROJ")
+Example: jira_list_boards(type="scrum")`,
+            inputSchema: z.object({
+                projectKeyOrId: z.string().optional().describe("Filter by project key or ID"),
+                type: z.enum(["scrum", "kanban"]).optional().describe("Filter by board type"),
+                name: z.string().optional().describe("Filter by board name (contains)"),
+            }),
+            handler: async (args) => {
+                try {
+                    const result = await requireClient().listBoards(args);
+                    const boards = (result.values || []).map(formatBoardMetadata);
+                    return formatSuccessJson(boards, {
+                        resourceType: "jira_boards",
+                        schemaType: "jira_board",
+                        title: "Jira Boards",
+                        total: result.total,
+                    });
+                }
+                catch (error) {
+                    return formatError(isApiError(error) ? error : new Error(String(error)));
+                }
+            },
+        },
         jira_get_board: {
             description: `Get information about an Agile board (Scrum or Kanban).
 
@@ -532,8 +686,13 @@ Example: jira_get_board(boardId=123)`,
             handler: async (args) => {
                 try {
                     const result = await requireClient().getBoard(args.boardId);
-                    return formatSuccessJson(result, {
+                    // Flatten board to match jira_board schema, keep raw data for extra fields
+                    return formatSuccessJson({
+                        ...formatBoardMetadata(result),
+                        data: result,
+                    }, {
                         resourceType: "jira_board",
+                        schemaType: "jira_board",
                         title: result.name || `Board #${args.boardId}`,
                         boardId: args.boardId,
                     });
@@ -563,8 +722,11 @@ Example: jira_get_sprints(boardId=123, state="active")`,
             handler: async (args) => {
                 try {
                     const result = await requireClient().getSprints(args.boardId, args.state);
-                    return formatSuccessJson(result, {
+                    // Flatten sprints to match jira_sprint schema
+                    const sprints = (result.values || result || []).map(formatSprintMetadata);
+                    return formatSuccessJson(sprints, {
                         resourceType: "jira_sprints",
+                        schemaType: "jira_sprint",
                         title: `Board #${args.boardId} sprints${args.state ? ` (${args.state})` : ""}`,
                         boardId: args.boardId,
                     });
@@ -581,7 +743,7 @@ Retrieve sprint backlog for analysis or reporting.
 
 REQUIRES: sprintId (from jira_get_sprints)
 RETURNS: bufferId with issues array
-NEXT: buffer_pipeline (for sprint report), buffer_get_items (for analysis)
+NEXT: buffer_transform (for sprint report), buffer_get_items (for analysis)
 
 Example: jira_get_sprint_issues(sprintId=456)`,
             inputSchema: z.object({
@@ -590,8 +752,11 @@ Example: jira_get_sprint_issues(sprintId=456)`,
             handler: async (args) => {
                 try {
                     const result = await requireClient().getSprintIssues(args.sprintId);
-                    return formatSuccessJson(result, {
+                    // Flatten issues to match jira_issue schema
+                    const issues = (result.issues || result || []).map(formatIssueMetadata);
+                    return formatSuccessJson(issues, {
                         resourceType: "jira_sprint_issues",
+                        schemaType: "jira_issue",
                         title: `Sprint #${args.sprintId} issues`,
                         sprintId: args.sprintId,
                     });
@@ -640,16 +805,19 @@ Example: jira_get_issue_worklogs(issueKey="PROJ-123")`,
             handler: async (args) => {
                 try {
                     const result = await requireClient().getIssueWorklogs(args.issueKey);
+                    // Flatten worklogs to match jira_worklog schema
+                    const worklogs = (result.worklogs || []).map((w) => formatWorklogMetadata(w, args.issueKey));
                     // Calculate total time spent
-                    const totalSeconds = result.worklogs.reduce((sum, w) => sum + (w.timeSpentSeconds || 0), 0);
+                    const totalSeconds = (result.worklogs || []).reduce((sum, w) => sum + (w.timeSpentSeconds || 0), 0);
                     return formatSuccessJson({
                         issueKey: args.issueKey,
                         worklogCount: result.total,
                         totalTimeSpentSeconds: totalSeconds,
                         totalTimeSpent: formatTimeSpent(totalSeconds),
-                        worklogs: result.worklogs,
+                        worklogs,
                     }, {
                         resourceType: "jira_worklogs",
+                        schemaType: "jira_worklog",
                         title: `${args.issueKey} worklogs`,
                         issueKey: args.issueKey,
                     });
@@ -666,7 +834,7 @@ Aggregates time from subtasks and Epic children. Ideal for Epic time reports.
 
 REQUIRES: issueKey (works best with Epics)
 RETURNS: bufferId with breakdown by issue, totalTimeSpent, issueCount
-NEXT: buffer_pipeline (for time report), workload_sum (for calculations)
+NEXT: buffer_transform (for time report), workload_sum (for calculations)
 
 Example: jira_get_total_worklogs(issueKey="PROJ-100") - returns all time on Epic + stories + tasks`,
             inputSchema: z.object({
@@ -677,6 +845,7 @@ Example: jira_get_total_worklogs(issueKey="PROJ-100") - returns all time on Epic
                     const result = await requireClient().getTotalWorklogs(args.issueKey);
                     return formatSuccessJson(result, {
                         resourceType: "jira_worklogs_total",
+                        schemaType: "jira_worklog_total",
                         title: `${args.issueKey} total worklogs (recursive)`,
                         issueKey: args.issueKey,
                     });
@@ -696,7 +865,7 @@ Automatically detects Epic Link and Parent Link fields. Handles:
 
 REQUIRES: parentKey (Epic, Initiative, or any parent issue)
 RETURNS: bufferId with child issues (same format as jira_search_issues)
-NEXT: buffer_pipeline (for reports), buffer_get_items (for analysis), jira_analyze_epic (for deep analysis)
+NEXT: buffer_transform (for reports), buffer_get_items (for analysis), jira_analyze_epic (for deep analysis)
 
 Example: jira_list_epic_children(parentKey="PROJ-100")
 Example: jira_list_epic_children(parentKey="PROJ-100", status="open", type="Story")`,
@@ -705,89 +874,83 @@ Example: jira_list_epic_children(parentKey="PROJ-100", status="open", type="Stor
                 type: z.string().optional().describe("Filter by issue type (Story, Task, Bug, etc.)"),
                 status: z.enum(["open", "closed", "all"]).optional().describe("Filter by status: open (unresolved), closed (resolved), all (default)"),
                 recursive: z.boolean().optional().describe("Include nested children recursively (default: false for direct children only)"),
-                fields: z.array(z.string()).optional().describe("Specific fields to return"),
+                fields: stringOrArray.optional().describe("Specific fields to return (string or array)"),
             }),
             handler: async (args) => {
                 try {
                     const parentKey = args.parentKey;
                     const recursive = args.recursive ?? false;
-                    // Build JQL patterns to find children
-                    const jqlClauses = [];
-                    // 1. Subtasks
-                    jqlClauses.push(`parent = ${parentKey}`);
-                    // 2. Epic Link children
+                    // Get field IDs once (cached in client)
                     const epicLinkFieldId = await requireClient().getEpicLinkFieldId();
-                    if (epicLinkFieldId) {
-                        jqlClauses.push(`cf[${epicLinkFieldId.replace("customfield_", "")}] = ${parentKey}`);
-                    }
-                    // 3. Parent Link children (Initiative → Epic)
                     const parentLinkFieldId = await requireClient().getParentLinkFieldId();
-                    if (parentLinkFieldId) {
-                        jqlClauses.push(`cf[${parentLinkFieldId.replace("customfield_", "")}] = ${parentKey}`);
-                    }
-                    // 4. Jira Cloud parentEpic
-                    jqlClauses.push(`parentEpic = ${parentKey}`);
-                    // Build combined JQL
-                    let jql = `(${jqlClauses.join(" OR ")})`;
-                    // Apply filters
-                    if (args.type) {
-                        jql += ` AND issuetype = "${args.type}"`;
-                    }
+                    // Build filters (language-independent using statusCategory)
+                    let statusFilter = "";
                     if (args.status === "open") {
-                        jql += " AND resolution = Unresolved";
+                        statusFilter = " AND statusCategory != Done";
                     }
                     else if (args.status === "closed") {
-                        jql += " AND resolution IS NOT EMPTY";
+                        statusFilter = " AND statusCategory = Done";
                     }
-                    jql += " ORDER BY key ASC";
-                    // Fetch direct children
-                    const result = await requireClient().searchIssuesAll(jql, args.fields, 1000);
-                    let allChildren = [...result.issues];
-                    // If recursive, fetch children of children
-                    if (recursive && allChildren.length > 0) {
-                        const visited = new Set([parentKey, ...allChildren.map(i => i.key)]);
-                        const collectRecursive = async (parentKeys) => {
-                            for (const pk of parentKeys) {
-                                // Build JQL for this parent's children
-                                const subClauses = [`parent = ${pk}`];
-                                if (epicLinkFieldId) {
-                                    subClauses.push(`cf[${epicLinkFieldId.replace("customfield_", "")}] = ${pk}`);
-                                }
-                                if (parentLinkFieldId) {
-                                    subClauses.push(`cf[${parentLinkFieldId.replace("customfield_", "")}] = ${pk}`);
-                                }
-                                subClauses.push(`parentEpic = ${pk}`);
-                                let subJql = `(${subClauses.join(" OR ")})`;
-                                if (args.type) {
-                                    subJql += ` AND issuetype = "${args.type}"`;
-                                }
-                                if (args.status === "open") {
-                                    subJql += " AND resolution = Unresolved";
-                                }
-                                else if (args.status === "closed") {
-                                    subJql += " AND resolution IS NOT EMPTY";
-                                }
-                                try {
-                                    const subResult = await requireClient().searchIssuesAll(subJql, args.fields, 500);
-                                    const newChildren = subResult.issues.filter(i => !visited.has(i.key));
-                                    for (const child of newChildren) {
-                                        visited.add(child.key);
-                                        allChildren.push(child);
-                                    }
-                                    // Recurse into new children
-                                    if (newChildren.length > 0) {
-                                        await collectRecursive(newChildren.map(i => i.key));
+                    let typeFilter = "";
+                    if (args.type) {
+                        typeFilter = ` AND issuetype = "${args.type}"`;
+                    }
+                    // Build JQL patterns for a given parent key
+                    // Each pattern is tried independently with try-catch
+                    const buildPatterns = (pk) => {
+                        const patterns = [];
+                        // 1. Subtasks (language-independent)
+                        patterns.push(`parent = ${pk}${typeFilter}${statusFilter} ORDER BY key ASC`);
+                        // 2. Epic Link children (language-independent via cf[ID])
+                        if (epicLinkFieldId) {
+                            patterns.push(`cf[${epicLinkFieldId.replace("customfield_", "")}] = ${pk}${typeFilter}${statusFilter} ORDER BY key ASC`);
+                        }
+                        // 3. Parent Link children - Initiative → Epic (language-independent via cf[ID])
+                        if (parentLinkFieldId) {
+                            patterns.push(`cf[${parentLinkFieldId.replace("customfield_", "")}] = ${pk}${typeFilter}${statusFilter} ORDER BY key ASC`);
+                        }
+                        return patterns;
+                    };
+                    const visited = new Set([parentKey]);
+                    const allChildren = [];
+                    // Collect children for a parent using try-catch-per-pattern
+                    const collectChildren = async (pk, maxResults) => {
+                        for (const jql of buildPatterns(pk)) {
+                            try {
+                                const result = await requireClient().searchIssuesAll(jql, args.fields, maxResults);
+                                for (const issue of result.issues) {
+                                    if (!visited.has(issue.key)) {
+                                        visited.add(issue.key);
+                                        allChildren.push(issue);
                                     }
                                 }
-                                catch {
-                                    // Pattern not supported for this parent
-                                }
+                                // Don't break - multiple patterns may find different children
+                            }
+                            catch {
+                                // Pattern not supported, try next
                             }
-                        };
-                        await collectRecursive(allChildren.map(i => i.key));
+                        }
+                    };
+                    // Fetch direct children
+                    const maxResults = getMaxApiResults();
+                    await collectChildren(parentKey, maxResults);
+                    const directChildCount = allChildren.length;
+                    // If recursive, fetch children of children
+                    if (recursive && directChildCount > 0) {
+                        let startIndex = 0;
+                        while (startIndex < allChildren.length) {
+                            const currentBatchEnd = allChildren.length;
+                            for (let i = startIndex; i < currentBatchEnd; i++) {
+                                await collectChildren(allChildren[i].key, maxResults);
+                            }
+                            startIndex = currentBatchEnd;
+                        }
                     }
+                    // Flatten issues to match jira_issue schema
+                    const flattenedChildren = allChildren.map(formatIssueMetadata);
                     const metadata = {
                         resourceType: "jira_epic_children",
+                        schemaType: "jira_issue",
                         title: `Children of ${parentKey}`,
                         parentKey,
                         recursive,
@@ -796,7 +959,7 @@ Example: jira_list_epic_children(parentKey="PROJ-100", status="open", type="Stor
                             status: args.status || "all",
                         },
                     };
-                    return formatSuccessJson(allChildren, metadata);
+                    return formatSuccessJson(flattenedChildren, metadata);
                 }
                 catch (error) {
                     return formatError(isApiError(error) ? error : new Error(String(error)));