Linear MCP Server

Instructions

Implementation Reference

• src/tools/list-issues.js:270-462 (handler)

  Primary ToolHandler for 'list_issues' tool. Processes inputs, creates Linear client, calls helper to fetch issues, formats output as numbered list with details, handles debug and errors.
  const handler = async ( ctx, { assignedToMe, assignee, status, project, sortBy, sortDirection, limit, debug, } ) => { const logger = ctx.effects.logger; try { // Log details about config and parameters logger.debug('List issues called with parameters:', { assignedToMe, assignee, status, project, sortBy, sortDirection, limit, debug, }); // Debug log for API key (masked) const apiKey = ctx.config.linearApiKey || ''; const maskedKey = apiKey ? apiKey.substring(0, 4) + '...' + apiKey.substring(apiKey.length - 4) : '<not set>'; logger.debug(`Using Linear API key: ${maskedKey}`); if (!ctx.config.linearApiKey) { throw new Error('LINEAR_API_KEY is not configured'); } // Create a Linear client using our effect logger.debug('Creating Linear client'); const linearClient = ctx.effects.linear.createClient( ctx.config.linearApiKey ); // List issues using the Linear SDK client with filters logger.debug('Executing Linear API list with filters'); const results = await listIssues( linearClient, { assignedToMe, assignee, status, project, }, { limit, sortBy, sortDirection, }, logger ); // Log the results count logger.info(`Found ${results.results.length} issues matching criteria`); // Format the output let responseText = ''; logger.info(`Result: ${JSON.stringify(results, null, 2)}`); if (results.results.length === 0) { responseText = 'No issues found matching your criteria.'; } else { responseText = 'Issues found:\n\n'; results.results.forEach((issue, index) => { const priorityMap = { 0: 'No priority', 1: 'Urgent', 2: 'High', 3: 'Medium', 4: 'Low', }; const priority = issue.priority ?? 0; // Format timestamps to be more readable const formatDate = timestamp => { if (!timestamp) return 'Unknown'; const date = new Date(timestamp); return date.toLocaleString(); }; responseText += `${index + 1}. ${issue.title || 'Untitled'}\n`; responseText += ` ID: ${issue.id}\n`; if (issue.identifier) { responseText += ` Identifier: ${issue.identifier}\n`; } if (issue.url) { responseText += ` URL: ${issue.url}\n`; } responseText += ` Status: ${issue.status || 'Unknown'}\n`; responseText += ` Priority: ${priorityMap[priority] || 'Unknown'}\n`; if (issue.project) { responseText += ` Project: ${issue.project.name}\n`; } if (issue.assignee) { responseText += ` Assignee: ${issue.assignee.name}\n`; } responseText += ` Created: ${formatDate(issue.createdAt)}\n`; responseText += ` Updated: ${formatDate(issue.updatedAt)}\n`; responseText += '\n'; }); } logger.debug('Returning formatted list results'); return { content: [{ type: 'text', text: responseText }], }; } catch (error) { logger.error(`Error listing issues: ${error.message}`); logger.error(error.stack); // Create a user-friendly error message with troubleshooting guidance let errorMessage = `Error listing issues: ${error.message}`; // Add detailed diagnostic information if in debug mode if (debug) { errorMessage += '\n\n=== DETAILED DEBUG INFORMATION ==='; // Add filter parameters that were used errorMessage += `\nFilter parameters: - assignedToMe: ${assignedToMe} - assignee: ${assignee || '<not specified>'} - status: ${status || '<not specified>'} - project: ${project || '<not specified>'} - sortBy: ${sortBy} - sortDirection: ${sortDirection} - limit: ${limit}`; // Check if API key is configured const apiKey = ctx.config.linearApiKey || ''; const keyStatus = apiKey ? `API key is configured (${apiKey.substring( 0, 4 )}...${apiKey.substring(apiKey.length - 4)})` : 'API key is NOT configured - set LINEAR_API_KEY'; errorMessage += `\n\nLinear API Status: ${keyStatus}`; // Add error details if (error.name) { errorMessage += `\nError type: ${error.name}`; } if (error.code) { errorMessage += `\nError code: ${error.code}`; } if (error.stack) { errorMessage += `\n\nStack trace: ${error.stack .split('\n') .slice(0, 3) .join('\n')}`; } // Add Linear API info for manual testing errorMessage += `\n\nLinear API: Using official Linear SDK (@linear/sdk) For manual testing, try using the SDK directly or the Linear API Explorer in the Linear UI.`; } // Add a note that debug mode can be enabled for more details if (!debug) { errorMessage += `\n\nFor more detailed diagnostics, retry with debug:true in the input.`; } return { content: [ { type: 'text', text: errorMessage, }, ], isError: true, }; } };
• src/tools/list-issues.js:25-34 (schema)

  Zod input schema defining parameters for filtering and sorting issues in the list_issues tool.
  const ListIssuesInputSchema = z.object({ assignedToMe: z.boolean().default(false), assignee: z.string().optional(), status: z.string().optional(), project: z.string().optional(), sortBy: z.enum(['createdAt', 'updatedAt']).default('createdAt'), sortDirection: z.enum(['ASC', 'DESC']).default('DESC'), limit: z.number().min(1).max(100).default(25), debug: z.boolean().default(false), // Debug mode to show extra diagnostics });
• src/tools/list-issues.js:467-473 (registration)

  Tool factory using create_tool to register 'list_issues' with name, description, schema, and handler.
  export const ListIssues = create_tool({ name: 'list_issues', description: 'List Linear issues (also called tickets) with filtering by assignee, status, and project. Use this to browse and find issues in your Linear workspace.', inputSchema: ListIssuesInputSchema, handler, });
• src/tools/list-issues.js:52-264 (helper)

  Core helper function that uses Linear SDK to query issues with filters, processes promises for related data (state, assignee, project), and returns validated results.
  async function listIssues( client, filters = {}, { limit = 25, sortBy, sortDirection = 'ASC' } = {}, logger ) { try { logger?.debug('Building Linear SDK filter parameters', { filters, limit, sortBy: sortBy || 'none', sortDirection, }); // Build filters properly using Linear SDK filter syntax const filter = {}; // Add assignee filter if (filters.assignedToMe) { // For assignedToMe we'll use the viewer API directly, // but we'll still build the filter for normal query as fallback filter.assignee = { id: { eq: 'me' } }; } else if (filters.assignee) { filter.assignee = { name: { eq: filters.assignee } }; } // Add status filter if (filters.status) { // Properly filter by state name filter.state = { name: { eq: filters.status } }; logger?.debug(`Filtering by state name: ${filters.status}`); } // Add project filter if (filters.project) { // Filter by project name filter.project = { name: { eq: filters.project } }; logger?.debug(`Filtering by project name: ${filters.project}`); } logger?.debug('Built filter object:', JSON.stringify(filter, null, 2)); // Use the sort direction as provided let direction = sortDirection; logger?.debug(`Using sort direction: ${direction} for field: ${sortBy}`); // Build search parameters const searchParams = { first: limit, }; // Add sort parameters if specified if (sortBy) { searchParams.orderBy = sortBy; searchParams.orderDirection = direction; } // Build the full GraphQL query parameters with proper filter const queryParams = { filter, // Use the properly constructed filter object ...searchParams, }; // Log the complete query parameters for debugging logger?.debug( 'Full Linear API query parameters:', JSON.stringify(queryParams, null, 2) ); let result; try { // First try using the viewer API which may be more reliable for getting assigned issues if (filters.assignedToMe) { logger?.debug( 'Using viewer.assignedIssues API for retrieving assigned issues' ); const me = await client.viewer; result = await me.assignedIssues(searchParams); logger?.debug('Successfully retrieved issues using viewer API'); } else { // Otherwise use the direct GraphQL API from Linear SDK logger?.debug('Using issues API for general issue search'); // @ts-ignore - The Linear SDK types are not accurate for the GraphQL API result = await client.issues(queryParams); logger?.debug('Successfully retrieved issues using issues API'); } } catch (error) { logger?.error(`Linear API error:`, error); throw error; } // Log the raw response structure (without full content) logger?.debug(`Linear API response structure:`, { hasNodes: !!result.nodes, nodeCount: result.nodes?.length || 0, firstNodeKeys: result.nodes?.[0] ? Object.keys(result.nodes[0]) : [], }); // Log search results at debug level logger?.debug(`Linear list returned ${result.nodes.length} results`); // Process issues from Linear SDK format to our domain model // The Linear SDK returns promises for many fields, so we need to await them const processedIssues = []; for (const issue of result.nodes) { try { logger?.debug(`Processing issue ${issue.id}`); // Get state/status information (it's a promise in the Linear SDK) let statusName = 'Unknown'; try { if (issue.state) { const state = await issue.state; if (state && state.name) { statusName = state.name; logger?.debug(`Found state: ${statusName}`); } } } catch (stateError) { logger?.warn(`Error fetching state data: ${stateError.message}`); } // Get assignee if present (it's a promise in the Linear SDK) let assigneeData = undefined; try { if (issue.assignee) { const assignee = await issue.assignee; if (assignee) { assigneeData = { id: assignee.id, name: assignee.name, email: assignee.email, }; logger?.debug(`Found assignee: ${assignee.name}`); } } } catch (assigneeError) { logger?.warn( `Error fetching assignee data: ${assigneeError.message}` ); } // Get project if present (it's a promise in the Linear SDK) let projectData = undefined; try { if (issue.project) { const project = await issue.project; if (project) { projectData = { id: project.id, name: project.name, }; logger?.debug(`Found project: ${project.name}`); } } } catch (projectError) { logger?.warn(`Error fetching project data: ${projectError.message}`); } const processedIssue = IssueSchema.parse({ id: issue.id, identifier: issue.identifier || undefined, // Add the issue identifier (e.g. TEAM-123) url: issue.url || undefined, // Add the issue URL for linking title: issue.title, description: issue.description || undefined, priority: issue.priority, assignee: assigneeData, project: projectData, status: statusName, createdAt: issue.createdAt, updatedAt: issue.updatedAt, }); processedIssues.push(processedIssue); } catch (processError) { logger?.error( `Error processing issue ${issue.id}: ${processError.message}` ); // Continue processing other issues even if one fails } } logger?.debug( `Successfully processed ${processedIssues.length}/${result.nodes.length} issues` ); const issues = processedIssues; // Return the processed results return SearchResultsSchema.parse({ results: issues }); } catch (error) { // Enhanced error logging logger?.error(`Error listing Linear issues: ${error.message}`, { filters, limit, sortBy, sortDirection, stack: error.stack, }); // Check if it's a Zod validation error (formatted differently) if (error.name === 'ZodError') { logger?.error( 'Zod validation error details:', JSON.stringify(error.errors, null, 2) ); } // Rethrow the error for the tool to handle throw error; } }
• src/index.js:109-118 (registration)

  Instantiation of ListIssues tool with context and inclusion in all_tools array for MCP server registration.
  const all_tools = [ new tools.ListIssues(toolContext), new tools.GetIssue(toolContext), new tools.ListMembers(toolContext), new tools.ListProjects(toolContext), new tools.GetProject(toolContext), new tools.ListTeams(toolContext), new tools.AddComment(toolContext), new tools.CreateIssue(toolContext), ];