Linear MCP Server

Instructions

Implementation Reference

• src/tools/list-teams.js:328-525 (handler)

  The primary handler function that implements the core logic for the 'list_teams' tool. It processes input parameters, interacts with the Linear API via effects, fetches and formats team data, and returns a structured text response or detailed error.

  const handler = async (
    ctx,
    { nameFilter, includeMembers, includeProjects, limit, debug }
  ) => {
    const logger = ctx.effects.logger;
  
    try {
      // Log details about parameters
      logger.debug('List teams called with parameters:', {
        nameFilter,
        includeMembers,
        includeProjects,
        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 teams using the Linear SDK client
      logger.debug('Executing Linear API to list teams');
      const results = await listTeams(
        linearClient,
        { nameFilter },
        { includeMembers, includeProjects, limit },
        logger
      );
  
      // Log the results count
      logger.info(`Found ${results.results.length} teams matching criteria`);
  
      // Format the output
      let responseText = '';
  
      if (results.results.length === 0) {
        responseText = 'No teams found matching your criteria.';
      } else {
        responseText = 'Teams found:\n\n';
  
        // Format dates for display
        const formatDisplayDate = timestamp => {
          if (!timestamp) return 'Not available';
          try {
            const date = new Date(timestamp);
            return date.toLocaleString();
          } catch (e) {
            return 'Invalid date';
          }
        };
  
        results.results.forEach((team, index) => {
          responseText += `${index + 1}. **${team.name}** (${team.key}) [ID: ${
            team.id
          }]\n`;
  
          if (team.description) {
            responseText += `   Description: ${team.description}\n`;
          }
  
          // Add metrics
          const memberCount = team.memberCount || 0;
          const projectCount = team.projectCount || 0;
          const issueCount = team.issueCount || 0;
          const completedIssueCount = team.completedIssueCount || 0;
  
          responseText += `   Members: ${memberCount} | Projects: ${projectCount} | Issues: ${completedIssueCount}/${issueCount} completed\n`;
  
          // Add created/updated dates
          if (team.createdAt) {
            responseText += `   Created: ${formatDisplayDate(team.createdAt)}\n`;
          }
  
          if (team.url) {
            responseText += `   URL: ${team.url}\n`;
          }
  
          // Add members if included
          if (team.members && team.members.length > 0) {
            responseText += `   Members: `;
            const memberNames = team.members
              .slice(0, 5)
              .map(m => m.displayName || m.name)
              .join(', ');
  
            responseText += memberNames;
  
            if (team.members.length > 5) {
              responseText += `, +${team.members.length - 5} more`;
            }
  
            responseText += '\n';
          }
  
          // Add projects if included
          if (team.projects && team.projects.length > 0) {
            responseText += `   Projects: `;
            const projectNames = team.projects
              .slice(0, 5)
              .map(p => p.name)
              .join(', ');
  
            responseText += projectNames;
  
            if (team.projects.length > 5) {
              responseText += `, +${team.projects.length - 5} more`;
            }
  
            responseText += '\n';
          }
  
          responseText += '\n';
        });
      }
  
      logger.debug('Returning formatted list results');
      return {
        content: [{ type: 'text', text: responseText }],
      };
    } catch (error) {
      logger.error(`Error listing teams: ${error.message}`);
      logger.error(error.stack);
  
      // Create a user-friendly error message with troubleshooting guidance
      let errorMessage = `Error listing teams: ${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 += `\nParameters:
  - nameFilter: ${nameFilter || '<not specified>'}
  - includeMembers: ${includeMembers}
  - includeProjects: ${includeProjects}
  - 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-teams.js:22-45 (schema)

  Zod input schema defining parameters for the list_teams tool, including optional filters and options for members, projects, limit, and debug mode.

  const ListTeamsInputSchema = z.object({
    nameFilter: z
      .string()
      .optional()
      .describe('Filter teams by name (partial match)'),
    includeMembers: z
      .boolean()
      .default(true)
      .describe('Include sparse member listing for each team'),
    includeProjects: z
      .boolean()
      .default(true)
      .describe('Include sparse project listing for each team'),
    limit: z
      .number()
      .min(1)
      .max(100)
      .default(25)
      .describe('Maximum number of teams to return'),
    debug: z
      .boolean()
      .default(false)
      .describe('Debug mode to show extra diagnostics'),
  });

• src/tools/list-teams.js:530-536 (registration)

  Tool factory registration using create_tool, specifying the name 'list_teams', description, input schema, and handler function.

  export const ListTeams = create_tool({
    name: 'list_teams',
    description:
      'List Linear teams with details about their members, projects, and issues. Use this to get a high-level view of all teams in your Linear workspace.',
    inputSchema: ListTeamsInputSchema,
    handler,
  });

• src/tools/list-teams.js:113-312 (helper)

  Core helper function that performs the actual Linear API interactions to list and enrich team data with members, projects, and metrics.

  async function listTeams(
    client,
    filters = {},
    { includeMembers = true, includeProjects = true, limit = 25 } = {},
    logger
  ) {
    try {
      logger?.debug('Building Linear SDK parameters', {
        filters,
        includeMembers,
        includeProjects,
        limit,
      });
  
      // Get all teams
      // @ts-ignore - The Linear SDK types may not be fully accurate
      const teamsResponse = await client.teams();
      logger?.debug(`Found ${teamsResponse.nodes.length} teams`);
  
      // Filter teams by name if specified
      let filteredTeams = teamsResponse.nodes;
      if (filters.nameFilter) {
        const nameFilterLower = filters.nameFilter.toLowerCase();
        logger?.debug(`Filtering teams by name: ${filters.nameFilter}`);
  
        filteredTeams = filteredTeams.filter(team => {
          const name = team.name.toLowerCase();
          const key = team.key.toLowerCase();
          const description = team.description?.toLowerCase() || '';
  
          // Check for direct inclusion
          if (
            name.includes(nameFilterLower) ||
            key.includes(nameFilterLower) ||
            description.includes(nameFilterLower)
          ) {
            return true;
          }
  
          // No match found
          return false;
        });
  
        logger?.debug(
          `After name filtering, found ${filteredTeams.length} teams`
        );
      }
  
      // Apply limit to teams
      filteredTeams = filteredTeams.slice(0, limit);
  
      // Process teams to extract detailed information
      const processedTeams = await Promise.all(
        filteredTeams.map(async team => {
          logger?.debug(`Processing team ${team.name} (${team.id})`);
  
          // Build base team object
          const teamData = {
            id: team.id,
            name: team.name,
            key: team.key,
            description: team.description,
            createdAt: formatDate(team.createdAt),
            updatedAt: formatDate(team.updatedAt),
            color: team.color,
            private: team.private,
            // @ts-ignore - SDK may have different property name
            cycleEnable: team.cyclesEnabled || team.cycleEnable,
            timezone: team.timezone,
            // @ts-ignore - SDK structure may differ from types
            markedAsDuplicate: team.markedAsDuplicate,
            // @ts-ignore - SDK structure may differ from types
            issuesPerCycle: team.issuesPerCycle,
            // @ts-ignore - SDK structure may differ from types
            url: team.url,
          };
  
          // Add members if requested
          if (includeMembers) {
            try {
              // @ts-ignore - The Linear SDK types may not be fully accurate
              const membersResponse = await team.members();
              if (membersResponse?.nodes) {
                teamData.members = membersResponse.nodes.map(member => ({
                  id: member.id,
                  name: member.name,
                  displayName: member.displayName || member.name,
                  active: member.active !== false,
                }));
                teamData.memberCount = teamData.members.length;
              }
              logger?.debug(
                `Added ${teamData.memberCount || 0} members for team ${team.name}`
              );
            } catch (membersError) {
              logger?.warn(
                `Error fetching members for team ${team.name}: ${membersError.message}`
              );
            }
          }
  
          // Add projects if requested
          if (includeProjects) {
            try {
              // @ts-ignore - The Linear SDK types may not be fully accurate
              const projectsResponse = await team.projects();
              if (projectsResponse?.nodes) {
                teamData.projects = await Promise.all(
                  projectsResponse.nodes.map(async project => {
                    // Get state information
                    let stateName = undefined;
                    try {
                      if (project.state) {
                        const state = await project.state;
                        if (state) {
                          // @ts-ignore - SDK structure may differ from types
                          stateName = state.name;
                        }
                      }
                    } catch (stateError) {
                      logger?.warn(
                        `Error fetching project state: ${stateError.message}`
                      );
                    }
  
                    return {
                      id: project.id,
                      name: project.name,
                      state: stateName,
                      // @ts-ignore - SDK has different property name
                      completed: project.completedAt ? true : false,
                    };
                  })
                );
                teamData.projectCount = teamData.projects.length;
              }
              logger?.debug(
                `Added ${teamData.projectCount || 0} projects for team ${
                  team.name
                }`
              );
            } catch (projectsError) {
              logger?.warn(
                `Error fetching projects for team ${team.name}: ${projectsError.message}`
              );
            }
          }
  
          // Add issue counts
          try {
            // @ts-ignore - The Linear SDK types may not be fully accurate
            const issuesResponse = await team.issues();
            if (issuesResponse) {
              teamData.issueCount = issuesResponse.nodes.length;
              teamData.activeIssueCount = issuesResponse.nodes.filter(
                issue => !issue.completedAt
              ).length;
              teamData.completedIssueCount = issuesResponse.nodes.filter(
                issue => issue.completedAt
              ).length;
            }
            logger?.debug(
              `Added issue counts for team ${team.name}: ${
                teamData.issueCount || 0
              } total`
            );
          } catch (issuesError) {
            logger?.warn(
              `Error fetching issues for team ${team.name}: ${issuesError.message}`
            );
          }
  
          return teamData;
        })
      );
  
      logger?.debug(`Successfully processed ${processedTeams.length} teams`);
      return TeamSearchResultsSchema.parse({ results: processedTeams });
    } catch (error) {
      // Enhanced error logging
      logger?.error(`Error listing Linear teams: ${error.message}`, {
        filters,
        includeMembers,
        includeProjects,
        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)

  Top-level MCP server registration: instantiates ListTeams at line 115 and registers it via server.tool in the loop (lines 121-149).

  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 },
          };
        }
      }
    );
  }