Faker MCP Server

Instructions

Implementation Reference

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

  Handler function for the generate-company MCP tool. Validates inputs using GenerateCompanySchema, creates a CompanyGenerator instance, generates the requested number of company records (single or batch), computes metadata including generation time, and returns an MCP-formatted response containing a text summary and a JSON resource with the generated data and metadata.
  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 validation schema defining all input parameters for the generate-company tool, including count, locale, seed, and optional flags for including additional 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/index.ts:20-22 (registration)

  Registers the generate-company tool with the MCP server by calling server.registerTool(generateCompanyTool, handleGenerateCompany), linking the tool definition and its handler function.
  // Register User Story 1 tools: generate-person and generate-company server.registerTool(generatePersonTool, handleGeneratePerson); server.registerTool(generateCompanyTool, handleGenerateCompany);
• src/tools/generate-company.ts:45-50 (registration)

  MCP Tool definition object for generate-company, including the name, description, and inputSchema converted from the Zod schema.
  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/generators/company-generator.ts:58-304 (helper)

  CompanyGenerator class that extends BaseGenerator and implements the core logic for generating single or multiple realistic company records using Faker.js, including company names, industries, emails, optional phone/website/founded/employee count/address fields, with locale and seed support.
  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; }); } }