Linear MCP Server

Instructions

Implementation Reference

• src/tools/add-comment.js:129-251 (handler)

  The main handler function for the 'add_comment' tool. It processes input parameters, creates a Linear client, calls the addComment helper, formats the success response or detailed error message, and returns MCP-compatible content.
  const handler = async (ctx, { ticketId, comment, debug }) => { const logger = ctx.effects.logger; try { // Log details about config and parameters logger.debug('Add comment called with parameters:', { ticketId, commentLength: comment?.length, 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 ); // Add the comment using the Linear SDK client logger.debug('Executing Linear API to add comment'); const result = await addComment(linearClient, ticketId, comment, logger); // Log that we created the comment logger.info(`Added comment to ticket ID: ${ticketId}`); // Format the output const formatDate = timestamp => { if (!timestamp) return 'Just now'; const date = new Date(timestamp); return date.toLocaleString(); }; let responseText = ''; responseText += `✅ Comment added successfully to ticket ${ticketId}\n\n`; // Add comment details responseText += `**Comment ID:** ${result.id}\n`; if (result.user) { responseText += `**Posted by:** ${result.user.name}\n`; } responseText += `**Posted at:** ${formatDate(result.createdAt)}\n\n`; responseText += `**Comment:**\n${result.body}\n`; logger.debug('Returning formatted comment result'); return { content: [{ type: 'text', text: responseText }], }; } catch (error) { logger.error(`Error adding comment: ${error.message}`); logger.error(error.stack); // Create a user-friendly error message with troubleshooting guidance let errorMessage = `Error adding comment: ${error.message}`; // Add detailed diagnostic information if in debug mode if (debug) { errorMessage += '\n\n=== DETAILED DEBUG INFORMATION ==='; // Add parameters that were used errorMessage += `\nParameters: - ticketId: ${ticketId} - comment length: ${comment?.length} characters`; // 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/add-comment.js:22-29 (schema)

  Zod input schema defining parameters for the add_comment tool: ticketId (string), comment (string), debug (boolean, optional).
  const AddCommentInputSchema = z.object({ ticketId: z.string().describe('The ID of the Linear ticket to comment on'), comment: z.string().describe('The comment text to add to the ticket'), debug: z .boolean() .default(false) .describe('Debug mode to show extra diagnostics'), });
• src/tools/add-comment.js:256-262 (registration)

  Tool factory using create_tool() that registers the 'add_comment' tool with its name, description, input schema, and handler function.
  export const AddComment = create_tool({ name: 'add_comment', description: 'Add a comment to a specific Linear ticket. This tool is useful for providing feedback, status updates, or additional information on existing tickets.', inputSchema: AddCommentInputSchema, handler, });
• src/tools/add-comment.js:40-123 (helper)

  Helper function that performs the actual Linear API call to add a comment to a ticket using the Linear SDK, including validation and error handling.
  async function addComment(client, ticketId, comment, logger) { try { logger?.debug(`Adding comment to Linear issue with ID: ${ticketId}`); // First verify the issue exists const issue = await client.issue(ticketId); if (!issue) { logger?.error(`Issue with ID ${ticketId} not found`); throw new Error(`Issue with ID ${ticketId} not found`); } logger?.debug(`Successfully found issue: ${issue.id}, adding comment`); // Create the comment using the Linear SDK // The Linear SDK expects a CommentCreateInput object const commentResult = await client.createComment({ // The issueId property is part of CommentCreateInput issueId: ticketId, // The body property is part of CommentCreateInput body: comment, }); if (!commentResult) { throw new Error('Failed to create comment, received null response'); } // CommentPayload contains a comment property that's a promise const commentData = await commentResult.comment; if (!commentData) { throw new Error('Failed to retrieve comment data from response'); } logger?.debug(`Successfully added comment: ${commentData.id}`); // Get current user information for the response const me = await client.viewer; let userData = undefined; if (me) { userData = { id: me.id, name: me.name, email: me.email, }; } // Process and validate the comment data using our schema const processedComment = CommentSchema.parse({ id: commentData.id, body: commentData.body, user: userData, createdAt: commentData.createdAt instanceof Date ? commentData.createdAt.toISOString() : commentData.createdAt, updatedAt: commentData.updatedAt instanceof Date ? commentData.updatedAt.toISOString() : commentData.updatedAt, }); return processedComment; } catch (error) { // Enhanced error logging logger?.error(`Error adding comment to Linear issue: ${error.message}`, { ticketId, commentLength: comment?.length, 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)

  Instantiation of the AddComment tool instance with context and registration loop that adds all tools (including add_comment) to the MCP server using server.tool().
  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 }, }; } } ); }