modus_get_performance_leaderboard

Instructions

Implementation Reference

• modus-mcp-server.js:901-928 (handler)

  The handler function for the 'modus_get_performance_leaderboard' tool. It extracts year, quarter, month, and limit arguments, calls the Modus API endpoint /api/sales/performance/leaderboard, computes summary statistics (top performers overall, metrics tracked, unique performers count), and returns the result.

  case "modus_get_performance_leaderboard": {
    const { year, quarter, month, limit = 6 } = args || {};
    const params = new URLSearchParams();
  
    if (year) params.append("year", year.toString());
    if (quarter) params.append("quarter", quarter.toString());
    if (month) params.append("month", month.toString());
    if (limit) params.append("limit", limit.toString());
  
    response = await modusApi.get(`/api/sales/performance/leaderboard?${params.toString()}`);
    const leaderboard = response.data;
  
    // Add summary statistics
    const summary = {
      topPerformersOverall: identifyTopPerformersOverall(leaderboard),
      metricsTracked: Object.keys(leaderboard || {}).length,
      totalUniquePerformers: countUniquePerformers(leaderboard),
    };
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({ summary, leaderboard }, null, 2),
        },
      ],
    };
  }

• modus-mcp-server.js:263-289 (schema)

  The input schema definition for the 'modus_get_performance_leaderboard' tool. Defines parameters: year (number), quarter (number 1-4), month (number 1-12), and limit (number, default 6).

  {
    name: "modus_get_performance_leaderboard",
    description:
      "Get top sales performers across key metrics including opportunities created/won, pipeline created, bookings, ASP, and close rate. Returns ranked list of top performers for each metric.",
    inputSchema: {
      type: "object",
      properties: {
        year: {
          type: "number",
          description: "Year for performance data",
        },
        quarter: {
          type: "number",
          description: "Quarter number (1-4)",
        },
        month: {
          type: "number",
          description: "Month number (1-12)",
        },
        limit: {
          type: "number",
          default: 6,
          description: "Number of top performers to show per metric",
        },
      },
    },
  },

• modus-mcp-server.js:263-289 (registration)

  The tool name 'modus_get_performance_leaderboard' is registered in the TOOLS array (line 264) and the corresponding handler case is in the switch statement (line 901).

  {
    name: "modus_get_performance_leaderboard",
    description:
      "Get top sales performers across key metrics including opportunities created/won, pipeline created, bookings, ASP, and close rate. Returns ranked list of top performers for each metric.",
    inputSchema: {
      type: "object",
      properties: {
        year: {
          type: "number",
          description: "Year for performance data",
        },
        quarter: {
          type: "number",
          description: "Quarter number (1-4)",
        },
        month: {
          type: "number",
          description: "Month number (1-12)",
        },
        limit: {
          type: "number",
          default: 6,
          description: "Number of top performers to show per metric",
        },
      },
    },
  },

• modus-mcp-server.js:1264-1283 (helper)

  Helper function 'identifyTopPerformersOverall' that counts appearances of performers across leaderboard metrics to identify top overall performers.

  function identifyTopPerformersOverall(leaderboard) {
    if (!leaderboard || typeof leaderboard !== "object") return [];
    const performerCounts = {};
  
    Object.keys(leaderboard).forEach((metric) => {
      if (Array.isArray(leaderboard[metric])) {
        leaderboard[metric].forEach((performer) => {
          const name = performer.employeeName || performer.name;
          if (name) {
            performerCounts[name] = (performerCounts[name] || 0) + 1;
          }
        });
      }
    });
  
    return Object.entries(performerCounts)
      .sort((a, b) => b[1] - a[1])
      .slice(0, 3)
      .map(([name, count]) => ({ name, appearances: count }));
  }

• modus-mcp-server.js:1285-1299 (helper)

  Helper function 'countUniquePerformers' that counts unique performer names across all leaderboard metrics.

  function countUniquePerformers(leaderboard) {
    if (!leaderboard || typeof leaderboard !== "object") return 0;
    const uniqueNames = new Set();
  
    Object.keys(leaderboard).forEach((metric) => {
      if (Array.isArray(leaderboard[metric])) {
        leaderboard[metric].forEach((performer) => {
          const name = performer.employeeName || performer.name;
          if (name) uniqueNames.add(name);
        });
      }
    });
  
    return uniqueNames.size;
  }