Linear MCP Server

Instructions

Implementation Reference

• src/tools/list-projects.js:506-730 (handler)

  The MCP ToolHandler function that executes the tool logic: processes validated input, creates Linear client using effects, calls the core listProjects function, formats detailed project list as text or error response.
  const handler = async ( ctx, { teamId, nameFilter, projectId, state, includeArchived, includeThroughIssues, fuzzyMatch, limit, debug, } ) => { const logger = ctx.effects.logger; try { // Log details about config and parameters logger.debug('List projects called with parameters:', { teamId, nameFilter, projectId, state, includeArchived, includeThroughIssues, fuzzyMatch, 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 projects using the Linear SDK client with filters logger.debug('Executing Linear API list with filters'); const results = await listProjects( linearClient, { teamId, nameFilter, projectId, state, includeArchived, includeThroughIssues, fuzzyMatch, }, { limit, }, logger ); // Log the results count logger.info(`Found ${results.results.length} projects matching criteria`); // Format the output let responseText = ''; if (results.results.length === 0) { responseText = 'No projects found matching your criteria.'; } else { responseText = 'Projects found:\n\n'; results.results.forEach((project, index) => { // Format dates for display const formatDisplayDate = timestamp => { if (!timestamp) return 'Not set'; try { const date = new Date(timestamp); return date.toLocaleString(); } catch (e) { return 'Invalid date'; } }; // Determine project status let status = 'Active'; if (project.archived) status = 'Archived'; else if (project.canceled) status = 'Canceled'; else if (project.completed) status = 'Completed'; else if (project.state) status = project.state; // Format completion percentage const progressPercent = Math.round(project.progress * 100); responseText += `${index + 1}. ${project.name} [ID: ${project.id}]\n`; if (project.description) { // Truncate description to keep output manageable const truncatedDescription = project.description.length > 100 ? project.description.substring(0, 97) + '...' : project.description; responseText += ` Description: ${truncatedDescription}\n`; } responseText += ` Status: ${status} (${progressPercent}% complete)\n`; if (project.teamName) { responseText += ` Team: ${project.teamName}\n`; } if (project.leadName) { responseText += ` Lead: ${project.leadName}\n`; } responseText += ` Issues: ${project.completedIssueCount}/${project.issueCount} completed\n`; // Add dates if (project.startDate) { responseText += ` Start date: ${formatDisplayDate( project.startDate )}\n`; } if (project.targetDate) { responseText += ` Target date: ${formatDisplayDate( project.targetDate )}\n`; } responseText += ` Created: ${formatDisplayDate(project.createdAt)}\n`; if (project.updatedAt) { responseText += ` Updated: ${formatDisplayDate( project.updatedAt )}\n`; } if (project.url) { responseText += ` URL: ${project.url}\n`; } responseText += '\n'; }); } logger.debug('Returning formatted list results'); return { content: [{ type: 'text', text: responseText }], }; } catch (error) { logger.error(`Error listing projects: ${error.message}`); logger.error(error.stack); // Create a user-friendly error message with troubleshooting guidance let errorMessage = `Error listing projects: ${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: - teamId: ${teamId || '<not specified>'} - nameFilter: ${nameFilter || '<not specified>'} - projectId: ${projectId || '<not specified>'} - state: ${state || '<not specified>'} - includeArchived: ${includeArchived} - includeThroughIssues: ${includeThroughIssues} - fuzzyMatch: ${fuzzyMatch} - 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-projects.js:27-37 (schema)

  Zod input schema for the list_projects tool defining optional filters and parameters.
  const ListProjectsInputSchema = z.object({ teamId: z.string().optional(), nameFilter: z.string().optional(), projectId: z.string().optional(), // Add direct project ID lookup state: z.enum(['active', 'completed', 'canceled', 'all']).optional(), // Add state filter includeArchived: z.boolean().default(false), includeThroughIssues: z.boolean().default(true), // Add option to include projects referenced by issues fuzzyMatch: z.boolean().default(true), // Enable fuzzy name matching by default limit: z.number().min(1).max(100).default(25), debug: z.boolean().default(false), // Debug mode to show extra diagnostics });
• src/tools/list-projects.js:735-741 (registration)

  Tool registration via create_tool factory exporting ListProjects with name, description, schema, and handler.
  export const ListProjects = create_tool({ name: 'list_projects', description: 'List Linear projects with optional filtering by team, name, and archive status. Shows project details including status, lead, progress, and dates.', inputSchema: ListProjectsInputSchema, handler, });
• src/tools/list-projects.js:94-302 (helper)

  Core helper function implementing Linear API queries, filtering (including fuzzy name matching), data enrichment from related entities, and result processing.
  async function listProjects(client, filters = {}, { limit = 25 } = {}, logger) { try { logger?.debug('Building Linear SDK filter parameters', { filters, limit, }); // Store all projects we find const allProjects = new Map(); // Direct lookup by project ID if specified if (filters.projectId) { logger?.debug(`Looking up project by ID: ${filters.projectId}`); try { // @ts-ignore - The Linear SDK types may not be fully accurate const project = await client.project(filters.projectId); if (project) { allProjects.set(project.id, project); logger?.debug(`Found project by ID: ${project.name} (${project.id})`); } } catch (projectError) { logger?.warn(`Error fetching project by ID: ${projectError.message}`); } } // Build query parameters for projects() method with all possible filters const queryParams = { first: Math.min(100, limit * 2), // Request enough projects but not too many includeArchived: filters.includeArchived, // Note: Removed orderBy parameter to fix TypeScript error // Would need to use the proper enum instead of a string }; // Initialize filter object queryParams.filter = {}; let hasFilter = false; // Apply state filter if provided if (filters.state && filters.state !== 'all') { queryParams.filter.state = { eq: filters.state }; hasFilter = true; logger?.debug(`Added state filter: ${filters.state}`); } // Apply team filter if provided if (filters.teamId) { queryParams.filter.team = { id: { eq: filters.teamId } }; hasFilter = true; logger?.debug(`Added team filter in projects query: ${filters.teamId}`); } // Apply name filter directly in the query if possible if (filters.nameFilter && !filters.fuzzyMatch) { // Only apply exact name filter here - fuzzy filtering will be done after fetching queryParams.filter.name = { contains: filters.nameFilter }; hasFilter = true; logger?.debug(`Added name filter: ${filters.nameFilter}`); } // If no filters applied, remove empty filter object if (!hasFilter) { delete queryParams.filter; } // No need to separately fetch team projects since we're already filtering by team in the main query // This simplifies the code and reduces API calls // Skip fetching all projects if we're just looking up by ID if (!filters.projectId) { // Get all projects regardless of team logger?.debug( 'Querying all projects with params:', JSON.stringify(queryParams, null, 2) ); try { // @ts-ignore - The Linear SDK types may not be fully accurate const projectsResponse = await client.projects(queryParams); logger?.debug( `Found ${projectsResponse.nodes.length} projects from direct query` ); // Add all projects to our collection for (const project of projectsResponse.nodes) { allProjects.set(project.id, project); } } catch (projectsError) { logger?.warn(`Error fetching projects: ${projectsError.message}`); } } // Add projects referenced by issues if enabled and we have fewer than expected projects // Only do this as a last resort if direct project queries don't yield enough results if ( filters.includeThroughIssues !== false && !filters.projectId && allProjects.size < limit ) { logger?.debug('Looking for additional projects referenced by issues'); try { // Build issue query parameters - only fetch what we need const issueQueryParams = { first: Math.min(30, limit), // Further reduce API load - we just need a few more projects // Removed orderBy parameter to fix TypeScript error - PaginationOrderBy enum is required }; // If we're filtering by team, also filter issues by team if (filters.teamId) { issueQueryParams.filter = { team: { id: { eq: filters.teamId } } }; } // Get issues and extract their projects in parallel const issuesResponse = await client.issues(issueQueryParams); if (issuesResponse.nodes.length > 0) { logger?.debug( `Found ${issuesResponse.nodes.length} issues to scan for projects` ); // Extract projects from issues all at once const projectPromises = issuesResponse.nodes .filter(issue => issue.project) // Only process issues with project references .map(async issue => { try { return await issue.project; } catch (error) { return null; } }); // Wait for all project promises to resolve in parallel const projects = await Promise.all(projectPromises); // Add valid projects to our collection projects .filter(project => project && !allProjects.has(project.id)) .forEach(project => { allProjects.set(project.id, project); logger?.debug(`Found additional project: ${project.name}`); }); } } catch (error) { logger?.warn(`Error fetching issues: ${error.message}`); } } logger?.debug( `Total projects found (before filtering): ${allProjects.size}` ); // Convert projects map to array let projectsArray = Array.from(allProjects.values()); // Apply name filtering if (filters.nameFilter) { projectsArray = filterProjectsByName( projectsArray, filters.nameFilter, filters.fuzzyMatch !== false, // Enable fuzzy matching unless explicitly disabled logger ); logger?.debug(`Projects after name filtering: ${projectsArray.length}`); } // Sort projects by updatedAt (most recent first) or name projectsArray.sort((a, b) => { if (a.updatedAt && b.updatedAt) { return ( new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime() ); } return a.name.localeCompare(b.name); }); // Apply limit projectsArray = projectsArray.slice(0, limit); logger?.debug( `Projects after limiting to ${limit}: ${projectsArray.length}` ); // Process projects to extract all relevant information const processedProjects = await processProjects(projectsArray, logger); logger?.debug( `Successfully processed ${processedProjects.length} projects` ); return ProjectSearchResultsSchema.parse({ results: processedProjects }); } catch (error) { // Enhanced error logging logger?.error(`Error listing Linear projects: ${error.message}`, { filters, limit, 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-149 (registration)

  Final MCP server registration: instantiates ListProjects and registers it with the server.tool() method alongside other tools.
  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), ]; // Register tools with the MCP server for (const tool of all_tools) { server.tool( tool.name, tool.description, tool.inputSchema.shape ?? {}, async args => { try { // Call our tool const result = await tool.call(args); // Return format expected by MCP SDK return { content: result.content, error: result.isError ? { message: result.content[0]?.text || 'An error occurred', } : undefined, }; } catch (error) { logger.error(`Error executing tool ${tool.name}: ${error.message}`); return { content: [{ type: 'text', text: `Error: ${error.message}` }], error: { message: error.message }, }; } } ); }