Cursor Pro Limits MCP Server

Instructions

Implementation Reference

• src/index.ts:212-253 (handler)

  The primary handler function for the 'get_service_usage' tool. It validates the input service parameter, fetches the usage data from the CursorLimitsMonitor, determines the status (OK/WARNING/CRITICAL), formats a detailed markdown response, and returns it.

    private async handleGetServiceUsage(args: { service: string }) {
      const { service } = args;
  
      if (!['sonnet45', 'gemini', 'gpt5', 'total'].includes(service)) {
        throw new Error(
          'Invalid service. Must be one of: sonnet45, gemini, gpt5, total'
        );
      }
  
      const usage = this.monitor.getServiceUsage(
        service as 'sonnet45' | 'gemini' | 'gpt5' | 'total'
      );
  
      const status = usage.isCritical
        ? '🔴 CRITICAL'
        : usage.isWarning
          ? '🟡 WARNING'
          : '🟢 OK';
  
      const content = `
  # ${service.toUpperCase()} Service Usage
  
  ## Status: ${status}
  
  - **Current**: ${usage.current}
  - **Maximum**: ${usage.max}
  - **Percentage**: ${usage.percentage.toFixed(1)}%
  - **Remaining**: ${usage.remaining}
  
  ${usage.isCritical ? '⚠️ This service is at or near its limit!' : ''}
  ${usage.isWarning ? '⚠️ This service is approaching its limit.' : ''}
      `.trim();
  
      return {
        content: [
          {
            type: 'text',
            text: content,
          },
        ],
      };
    }

• src/types.ts:73-82 (schema)

  Type definition for ServiceUsage, which represents the output structure returned by the tool handler and the getServiceUsage helper.

  export interface ServiceUsage {
    service: ServiceType;
    current: number;
    max: number;
    percentage: number;
    remaining: number;
    isWarning: boolean;
    isCritical: boolean;
  }

• src/index.ts:48-62 (registration)

  Registration of the 'get_service_usage' tool in the ListTools response, including name, description, and JSON input schema for validation.

  {
    name: 'get_service_usage',
    description: 'Get usage statistics for a specific service',
    inputSchema: {
      type: 'object',
      properties: {
        service: {
          type: 'string',
          enum: ['sonnet45', 'gemini', 'gpt5', 'total'],
          description: 'Service to check usage for',
        },
      },
      required: ['service'],
    },
  },

• src/types.ts:71-72 (schema)

  Type definition for ServiceType, used in the input schema enum and ServiceUsage interface.

  export type ServiceType = 'sonnet45' | 'gemini' | 'gpt5' | 'total';

• src/cursorLimitsMonitor.ts:149-167 (helper)

  Helper method in CursorLimitsMonitor that computes detailed usage statistics for a specific service, including current usage, max quota, percentage, remaining, and warning/critical flags.

  public getServiceUsage(
    service: 'sonnet45' | 'gemini' | 'gpt5' | 'total'
  ): ServiceUsage {
    const stats = this.getUsageStats();
    const current = this.getCurrentUsage(service);
    const max = this.getMaxUsage(service);
    const percentage = stats.usagePercentages[service];
    const remaining = stats.remaining[service];
  
    return {
      service,
      current,
      max,
      percentage,
      remaining,
      isWarning: percentage >= 0.8,
      isCritical: percentage >= 0.95,
    };
  }