generate-company

Instructions

Implementation Reference

• src/tools/generate-company.ts:71-142 (handler)

  The main handler function for the 'generate-company' tool. It parses input parameters using Zod, creates a CompanyGenerator instance, generates the requested number of company records, builds metadata, and returns an MCP-compatible response containing a text summary and a JSON resource with the generated data.

  export function handleGenerateCompany(args: unknown): Promise<{ content: unknown[] }> {
    const startTime = Date.now();
  
    try {
      // Validate and parse arguments
      const params = GenerateCompanySchema.parse(args);
  
      // Create generator
      const generator = new CompanyGenerator({
        seed: params.seed,
        locale: params.locale,
      });
  
      // Generate data
      const data =
        params.count === 1
          ? [
              generator.generate({
                includeAddress: params.includeAddress,
                includeWebsite: params.includeWebsite,
                includePhone: params.includePhone,
                includeFoundedYear: params.includeFoundedYear,
                includeEmployeeCount: params.includeEmployeeCount,
              }),
            ]
          : generator.generateMany(params.count, {
              includeAddress: params.includeAddress,
              includeWebsite: params.includeWebsite,
              includePhone: params.includePhone,
              includeFoundedYear: params.includeFoundedYear,
              includeEmployeeCount: params.includeEmployeeCount,
            });
  
      const generationTimeMs = Date.now() - startTime;
  
      // Build response
      const metadata = {
        count: data.length,
        seed: generator.getSeed(),
        locale: generator.getLocale(),
        generationTimeMs,
      };
  
      const responseText = params.seed
        ? `Generated ${data.length} company record${data.length > 1 ? 's' : ''} with seed ${params.seed}`
        : `Generated ${data.length} company record${data.length > 1 ? 's' : ''}`;
  
      return Promise.resolve({
        content: [
          {
            type: 'text',
            text: responseText,
          },
          {
            type: 'resource',
            resource: {
              uri: 'faker://companies/generated',
              mimeType: 'application/json',
              text: JSON.stringify({ data, metadata }, null, 2),
            },
          },
        ],
      });
    } catch (error) {
      if (error instanceof z.ZodError) {
        throw new Error(
          `Invalid parameters: ${error.errors.map((e) => `${e.path.join('.')}: ${e.message}`).join(', ')}`
        );
      }
      throw error;
    }
  }

• src/tools/generate-company.ts:14-26 (schema)

  Zod schema for validating input parameters to the generate-company tool, including count, locale, seed, and flags for optional fields like address, website, phone, founded year, and employee count.

  export const GenerateCompanySchema = z.object({
    count: z.number().min(1).max(10000).default(1).describe('Number of company records to generate'),
    locale: z
      .nativeEnum(SupportedLocale)
      .default(SupportedLocale.EN)
      .describe('Locale for generated data'),
    seed: z.number().optional().describe('Optional seed for reproducible generation'),
    includeAddress: z.boolean().default(true).describe('Whether to include address information'),
    includeWebsite: z.boolean().default(true).describe('Whether to include website URL'),
    includePhone: z.boolean().default(true).describe('Whether to include phone number'),
    includeFoundedYear: z.boolean().default(false).describe('Whether to include founded year'),
    includeEmployeeCount: z.boolean().default(false).describe('Whether to include employee count'),
  });

• src/tools/generate-company.ts:45-50 (registration)

  Tool metadata definition for 'generate-company', including name, description, and JSON schema derived from Zod schema for MCP tool registration.

  export const generateCompanyTool: Tool = {
    name: 'generate-company',
    description:
      'Generates fake company data including names, industries, contact information, and addresses',
    inputSchema: zodToJsonSchema(GenerateCompanySchema) as Tool['inputSchema'],
  };

• src/index.ts:20-22 (registration)

  Registration of the generate-company tool handler with the FakerMCPServer instance in the main entry point.

  // Register User Story 1 tools: generate-person and generate-company
  server.registerTool(generatePersonTool, handleGeneratePerson);
  server.registerTool(generateCompanyTool, handleGenerateCompany);

• src/generators/company-generator.ts:58-304 (helper)

  CompanyGenerator class extending BaseGenerator, containing the core logic for generating single or multiple company records with faker.js, including industry selection, contact info, address, founded year, and weighted employee counts.

  export class CompanyGenerator extends BaseGenerator {
    /**
     * Creates a new CompanyGenerator instance.
     *
     * @constructor
     * @param {BaseGeneratorOptions} [options={}] - Generator configuration options
     * @example
     * ```typescript
     * const generator = new CompanyGenerator({
     *   locale: SupportedLocale.DE,
     *   seed: 12345
     * });
     * ```
     */
    constructor(options: BaseGeneratorOptions = {}) {
      super(options);
    }
  
    /**
     * Gets an industry name with locale-specific fallback.
     * Uses buzzNoun if available in the locale, otherwise falls back to generic industries.
     *
     * @private
     * @returns {string} An industry name
     * @example
     * ```typescript
     * const industry = this.getIndustry();
     * // Returns: 'Technology', 'Finance', 'Manufacturing', etc.
     * ```
     */
    private getIndustry(): string {
      try {
        return this.faker.company.buzzNoun();
      } catch {
        // Fallback to generic industries for locales without buzzNoun
        const industries = [
          'Technology',
          'Manufacturing',
          'Retail',
          'Healthcare',
          'Finance',
          'Education',
          'Consulting',
          'Real Estate',
          'Transportation',
          'Hospitality',
        ];
        return this.faker.helpers.arrayElement(industries);
      }
    }
  
    /**
     * Generates a single company record with complete business information.
     *
     * @param {CompanyGenerationOptions} [options={}] - Options controlling which fields to include
     * @returns {CompanyData} A company data object
     * @example
     * ```typescript
     * const company = generator.generate({
     *   includeAddress: true,
     *   includeWebsite: true,
     *   includeFoundedYear: true,
     *   includeEmployeeCount: true
     * });
     * // Returns: {
     * //   id: 'company_12345_0',
     * //   name: 'Acme Corporation',
     * //   industry: 'Technology',
     * //   email: 'acme@contact.com',
     * //   phone: '+1-555-987-6543',
     * //   website: 'https://acme.com',
     * //   founded: 1995,
     * //   employeeCount: 150,
     * //   address: { ... }
     * // }
     * ```
     */
    public generate(options: CompanyGenerationOptions = {}): CompanyData {
      const {
        includeAddress = true,
        includePhone = true,
        includeWebsite = true,
        includeFoundedYear = false,
        includeEmployeeCount = false,
      } = options;
  
      const companyName = this.faker.company.name();
  
      const company: CompanyData = {
        id: this.generateId('company', 0),
        name: companyName,
        industry: this.getIndustry(),
        email: this.faker.internet
          .email({
            firstName: companyName.split(' ')[0]?.toLowerCase() ?? 'info',
            lastName: 'contact',
          })
          .toLowerCase(),
      };
  
      if (includePhone) {
        company.phone = this.faker.phone.number();
      }
  
      if (includeWebsite) {
        company.website = this.faker.internet.url();
      }
  
      if (includeFoundedYear) {
        company.founded = this.faker.date
          .between({ from: '1900-01-01', to: new Date() })
          .getFullYear();
      }
  
      if (includeEmployeeCount) {
        // Generate employee count weighted towards smaller companies
        const weights = [0.5, 0.3, 0.15, 0.05]; // 50% small, 30% medium, 15% large, 5% enterprise
        const ranges = [
          { min: 1, max: 50 },
          { min: 51, max: 500 },
          { min: 501, max: 5000 },
          { min: 5001, max: 50000 },
        ];
  
        const rand = Math.random();
        let cumulative = 0;
        let range = ranges[0] ?? { min: 1, max: 50 };
  
        for (let i = 0; i < weights.length; i++) {
          cumulative += weights[i] ?? 0;
          if (rand < cumulative) {
            range = ranges[i] ?? { min: 1, max: 50 };
            break;
          }
        }
  
        company.employeeCount = this.faker.number.int({ min: range.min, max: range.max });
      }
  
      if (includeAddress) {
        company.address = {
          street: this.faker.location.streetAddress(),
          city: this.faker.location.city(),
          state: this.faker.location.state(),
          postalCode: this.faker.location.zipCode(),
          country: this.faker.location.country(),
        };
      }
  
      return company;
    }
  
    /**
     * Generates multiple company records efficiently.
     * Uses batch processing for large datasets to optimize memory usage.
     * Employee counts are weighted toward smaller companies (realistic distribution).
     *
     * @param {number} count - Number of company records to generate
     * @param {CompanyGenerationOptions} [options={}] - Options controlling which fields to include
     * @returns {CompanyData[]} Array of company data objects
     * @example
     * ```typescript
     * const companies = generator.generateMany(100, {
     *   includeAddress: true,
     *   includeWebsite: true,
     *   includeFoundedYear: true,
     *   includeEmployeeCount: true
     * });
     * console.log(`Generated ${companies.length} companies`);
     * ```
     */
    public generateMany(count: number, options: CompanyGenerationOptions = {}): CompanyData[] {
      return this.batchGenerate(count, (index) => {
        const {
          includeAddress = true,
          includePhone = true,
          includeWebsite = true,
          includeFoundedYear = false,
          includeEmployeeCount = false,
        } = options;
  
        const companyName = this.faker.company.name();
  
        const company: CompanyData = {
          id: this.generateId('company', index),
          name: companyName,
          industry: this.getIndustry(),
          email: this.faker.internet
            .email({
              firstName: companyName.split(' ')[0]?.toLowerCase() ?? 'info',
              lastName: 'contact',
            })
            .toLowerCase(),
        };
  
        if (includePhone) {
          company.phone = this.faker.phone.number();
        }
  
        if (includeWebsite) {
          company.website = this.faker.internet.url();
        }
  
        if (includeFoundedYear) {
          company.founded = this.faker.date
            .between({ from: '1900-01-01', to: new Date() })
            .getFullYear();
        }
  
        if (includeEmployeeCount) {
          const weights = [0.5, 0.3, 0.15, 0.05];
          const ranges = [
            { min: 1, max: 50 },
            { min: 51, max: 500 },
            { min: 501, max: 5000 },
            { min: 5001, max: 50000 },
          ];
  
          const rand = Math.random();
          let cumulative = 0;
          let range = ranges[0] ?? { min: 1, max: 50 };
  
          for (let i = 0; i < weights.length; i++) {
            cumulative += weights[i] ?? 0;
            if (rand < cumulative) {
              range = ranges[i] ?? { min: 1, max: 50 };
              break;
            }
          }
  
          company.employeeCount = this.faker.number.int({ min: range.min, max: range.max });
        }
  
        if (includeAddress) {
          company.address = {
            street: this.faker.location.streetAddress(),
            city: this.faker.location.city(),
            state: this.faker.location.state(),
            postalCode: this.faker.location.zipCode(),
            country: this.faker.location.country(),
          };
        }
  
        return company;
      });
    }
  }