jira_search_issues
Search for Jira issues using JQL queries to find specific tickets, filter by project, status, assignee, or other criteria with pagination and field selection.
Instructions
Search for Jira issues using JQL. Supports complex queries with pagination and field selection. Examples: "project = PROJECT AND status = Open", "assignee = currentUser()".
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| expand | No | Additional details to include for each issue | |
| fields | No | Specific fields to retrieve for each issue | |
| jql | Yes | JQL query string (e.g., "project = PROJECT AND status = Open") | |
| maxResults | No | Maximum number of results to return | |
| startAt | No | Index of first result to return (for pagination) |
Implementation Reference
- src/tools/search-issues.ts:52-76 (handler)The main handler function that executes the jira_search_issues tool logic: validates input, calls the Jira API via searchIssues helper, formats response, and handles errors.export async function handleSearchIssues(input: unknown): Promise<McpToolResponse> { try { const validated = validateInput(SearchIssuesInputSchema, input); log.info(`Searching issues with JQL: "${validated.jql}"...`); const searchParams: any = { jql: validated.jql, }; if (validated.nextPageToken !== undefined) searchParams.nextPageToken = validated.nextPageToken; if (validated.maxResults !== undefined) searchParams.maxResults = validated.maxResults; if (validated.fields !== undefined) searchParams.fields = validated.fields; if (validated.expand !== undefined) searchParams.expand = validated.expand; const result = await searchIssues(searchParams); log.info(`Found ${result.total ?? 0} issue(s), showing ${result.issues.length}`); return formatSearchResultsResponse(result); } catch (error) { log.error('Error in handleSearchIssues:', error); return handleError(error); } }
- src/types/tools.ts:27-45 (schema)Zod input schema for validating parameters to the jira_search_issues tool, used within the handler.export const SearchIssuesInputSchema = z.object({ jql: z.string().min(1).describe('JQL query string'), nextPageToken: z .string() .optional() .describe( 'Token for pagination. Omit for first page, use value from previous response for next page.' ), maxResults: z .number() .min(1) .max(100) .default(50) .describe('Maximum number of results to return per page'), fields: z.array(z.string()).optional().describe('Specific fields to retrieve'), expand: z.array(z.string()).optional().describe('Additional details to include'), }); export type SearchIssuesInput = z.infer<typeof SearchIssuesInputSchema>;
- src/index.ts:32-49 (registration)Central registration of all tool handlers in a Map, including the mapping for jira_search_issues to its handleSearchIssues function.const toolHandlers = new Map<string, (input: unknown) => Promise<any>>([ [TOOL_NAMES.GET_VISIBLE_PROJECTS, tools.handleGetVisibleProjects], [TOOL_NAMES.GET_ISSUE, tools.handleGetIssue], [TOOL_NAMES.SEARCH_ISSUES, tools.handleSearchIssues], [TOOL_NAMES.GET_MY_ISSUES, tools.handleGetMyIssues], [TOOL_NAMES.GET_ISSUE_TYPES, tools.handleGetIssueTypes], [TOOL_NAMES.GET_USERS, tools.handleGetUsers], [TOOL_NAMES.GET_PRIORITIES, tools.handleGetPriorities], [TOOL_NAMES.GET_STATUSES, tools.handleGetStatuses], [TOOL_NAMES.CREATE_ISSUE, tools.handleCreateIssue], [TOOL_NAMES.UPDATE_ISSUE, tools.handleUpdateIssue], [TOOL_NAMES.ADD_COMMENT, tools.handleAddComment], [TOOL_NAMES.GET_PROJECT_INFO, tools.handleGetProjectInfo], [TOOL_NAMES.CREATE_SUBTASK, tools.handleCreateSubtask], [TOOL_NAMES.GET_CREATE_META, tools.handleGetCreateMeta], [TOOL_NAMES.GET_CUSTOM_FIELDS, tools.handleGetCustomFields], [TOOL_NAMES.CREATE_ISSUE_LINK, tools.handleCreateIssueLink], ]);
- src/tools/search-issues.ts:13-50 (registration)Tool object definition including name, description, and input schema, exported for use in server tool listing.export const searchIssuesTool: Tool = { name: TOOL_NAMES.SEARCH_ISSUES, description: 'Search for Jira issues using JQL. Supports complex queries with pagination and field selection. Examples: "project = PROJECT AND status = Open", "assignee = currentUser()". For pagination, use nextPageToken from previous response.', inputSchema: { type: 'object', properties: { jql: { type: 'string', description: 'JQL query string (e.g., "project = PROJECT AND status = Open")', }, nextPageToken: { type: 'string', description: 'Token for pagination. Omit for first page, use value from previous response for next page.', }, maxResults: { type: 'number', description: 'Maximum number of results to return per page', minimum: 1, maximum: 100, default: 50, }, fields: { type: 'array', items: { type: 'string' }, description: 'Specific fields to retrieve for each issue', }, expand: { type: 'array', items: { type: 'string' }, description: 'Additional details to include for each issue', default: [], }, }, required: ['jql'], }, };
- src/index.ts:35-35 (registration)Specific registration entry mapping the tool name to its handler function.[TOOL_NAMES.SEARCH_ISSUES, tools.handleSearchIssues],
- src/config/constants.ts:27-27 (helper)Constant definition for the tool name used across the codebase.SEARCH_ISSUES: 'jira_search_issues',