Random.org MCP Server

Instructions

Implementation Reference

• src/server.ts:301-318 (handler)

  MCP tool handler that delegates to RandomOrgClient.generateIntegers and formats the result as MCP content response.

  private async handleGenerateIntegers(args: any) {
    const result = await this.randomOrgClient.generateIntegers(args);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            data: result.random.data,
            completionTime: result.random.completionTime,
            bitsUsed: result.bitsUsed,
            bitsLeft: result.bitsLeft,
            requestsLeft: result.requestsLeft,
            advisoryDelay: result.advisoryDelay,
          }, null, 2),
        },
      ],
    };
  }

• src/server.ts:38-76 (registration)

  Registration of the generateIntegers tool in the ListTools handler, including description and input JSON schema.

  {
    name: 'generateIntegers',
    description: 'Generate true random integers within a specified range',
    inputSchema: {
      type: 'object',
      properties: {
        n: {
          type: 'number',
          description: 'Number of integers to generate (1-10,000)',
          minimum: 1,
          maximum: 10000,
        },
        min: {
          type: 'number',
          description: 'Minimum value (inclusive)',
          minimum: -1000000000,
          maximum: 1000000000,
        },
        max: {
          type: 'number',
          description: 'Maximum value (inclusive)',
          minimum: -1000000000,
          maximum: 1000000000,
        },
        replacement: {
          type: 'boolean',
          description: 'Allow replacement (duplicates)',
          default: true,
        },
        base: {
          type: 'number',
          description: 'Number base (2, 8, 10, or 16)',
          enum: [2, 8, 10, 16],
          default: 10,
        },
      },
      required: ['n', 'min', 'max'],
    },
  },

• src/types.ts:113-119 (schema)

  TypeScript interface for input parameters (IntegerParams) used in generateIntegers.

  export interface IntegerParams {
    n: number;
    min: number;
    max: number;
    replacement?: boolean;
    base?: number;
  }

• src/randomOrgClient.ts:83-86 (helper)

  Core helper method that validates parameters and makes the JSON-RPC request to random.org API for generateIntegers.

  async generateIntegers(params: IntegerParams): Promise<IntegerResult> {
    this.validateIntegerParams(params);
    return this.makeRequest<IntegerResult>('generateIntegers', params);
  }

• src/randomOrgClient.ts:123-139 (helper)

  Input validation helper for generateIntegers parameters.

  private validateIntegerParams(params: IntegerParams): void {
    if (params.n < 1 || params.n > 10000) {
      throw new Error('n must be between 1 and 10,000');
    }
    if (params.min < -1000000000 || params.min > 1000000000) {
      throw new Error('min must be between -1,000,000,000 and 1,000,000,000');
    }
    if (params.max < -1000000000 || params.max > 1000000000) {
      throw new Error('max must be between -1,000,000,000 and 1,000,000,000');
    }
    if (params.min >= params.max) {
      throw new Error('min must be less than max');
    }
    if (params.base && ![2, 8, 10, 16].includes(params.base)) {
      throw new Error('base must be 2, 8, 10, or 16');
    }
  }