Faker MCP

🚀 Faker MCP 服務器

Faker MCP 服務器是一個基於 Model Context Protocol (MCP) 的服務器，它藉助 Faker.js 庫實現了偽造/模擬數據的生成功能。該服務器可用於為數據庫填充、API 測試、演示應用程序以及開發環境生成逼真的測試數據。

你可以在我的博客文章中瞭解更多關於為何以及何時使用此 MCP 服務器的信息。

✨ 主要特性

• 基礎數據生成：生成包含姓名、電子郵件、地址和聯繫信息的逼真個人和公司數據。
• 結構化數據集：為複雜的測試場景創建具有引用完整性的多實體數據集。
• 自定義模式：根據自定義模式（正則表達式、枚舉、格式、範圍）生成特定領域需求的數據。
• 多語言支持：支持生成英語、法語、德語、西班牙語和日語的數據。
• 可重現數據：基於種子生成一致的測試數據。
• 高性能：每秒可生成 1000 條以上的記錄。
• 符合 MCP 協議：可與兼容 MCP 的客戶端無縫集成。

📦 安裝指南

前提條件

• 系統中已安裝 Node.js 18 或更高版本。
• 擁有一個兼容 MCP 的客戶端（例如，Claude Desktop、Cline、Cursor 或任何 MCP 客戶端）。

🚀 快速開始

將 Faker MCP 服務器添加到 mcpServers 部分：

{
  "mcpServers": {
    "faker": {
      "command": "npx",
      "args": ["faker-mcp-server"]
    }
  }
}

有關各種 MCP 客戶端的詳細設置說明，請參閱MCP 客戶端配置部分。

💻 使用示例

可用工具

Faker MCP 服務器提供了四個強大的偽造數據生成工具：

1. generate-person

生成包含姓名、電子郵件、電話號碼和地址的逼真個人數據。 參數：

• count（數字，可選）：要生成的個人記錄數量（1 - 10,000，默認值：1）。
• locale（字符串，可選）：生成數據的語言環境 - en、fr、de、es、ja（默認值：en）。
• seed（數字，可選）：用於可重現生成的種子。
• includeAddress（布爾值，可選）：是否包含地址信息（默認值：true）。
• includePhone（布爾值，可選）：是否包含電話號碼（默認值：true）。
• includeDateOfBirth（布爾值，可選）：是否包含出生日期（默認值：false）。

示例用法：

生成 10 條包含姓名、電子郵件和地址的偽造個人記錄

示例請求（MCP 協議）：

{
  "method": "tools/call",
  "params": {
    "name": "generate-person",
    "arguments": {
      "count": 5,
      "locale": "en",
      "seed": 12345,
      "includeAddress": true,
      "includePhone": true,
      "includeDateOfBirth": false
    }
  }
}

示例輸出：

[
  {
    "id": "person_12345_0",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+1-555-123-4567",
    "address": {
      "street": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "postalCode": "62701",
      "country": "United States"
    }
  }
]

2. generate-company

生成包含名稱、行業、聯繫信息和地址的逼真公司數據。 參數：

• count（數字，可選）：要生成的公司記錄數量（1 - 10,000，默認值：1）。
• locale（字符串，可選）：生成數據的語言環境 - en、fr、de、es、ja（默認值：en）。
• seed（數字，可選）：用於可重現生成的種子。
• includeAddress（布爾值，可選）：是否包含地址信息（默認值：true）。
• includeWebsite（布爾值，可選）：是否包含網站 URL（默認值：true）。
• includeFoundedYear（布爾值，可選）：是否包含成立年份（默認值：false）。
• includeEmployeeCount（布爾值，可選）：是否包含員工數量（默認值：false）。

示例用法：

生成 5 條具有種子 54321 的公司記錄，以實現可重現性

示例請求（MCP 協議）：

{
  "method": "tools/call",
  "params": {
    "name": "generate-company",
    "arguments": {
      "count": 3,
      "locale": "en",
      "seed": 54321,
      "includeAddress": true,
      "includeWebsite": true,
      "includeFoundedYear": true,
      "includeEmployeeCount": true
    }
  }
}

示例輸出：

[
  {
    "id": "company_54321_0",
    "name": "Acme Corporation",
    "industry": "Technology",
    "email": "contact@acme.example.com",
    "phone": "+1-555-111-2222",
    "website": "https://acme.example.com",
    "address": {
      "street": "100 Tech Blvd",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "country": "United States"
    },
    "founded": 2010,
    "employeeCount": 250
  }
]

3. generate-dataset

生成具有多個實體類型和它們之間引用完整性的結構化數據集。 參數：

• schema（對象，必需）：定義實體和關係的數據集架構。
  • entities（對象）：實體名稱到實體定義的映射。
    • count（數字）：為該實體生成的記錄數量（1 - 10,000）。
    • type（字符串）：實體類型 - person、company 或 custom。
    • fields（數組，可選）：要包含的字段列表（默認為所有字段）。
    • relationships（對象，可選）：與其他實體的外鍵關係。
      • references（字符串）：父實體的名稱。
      • type（字符串）：關係類型 - one-to-many 或 many-to-many。
      • nullable（布爾值，可選）：外鍵是否可以為空（默認值：false）。
• locale（字符串，可選）：生成數據的語言環境 - en、fr、de、es、ja（默認值：en）。
• seed（數字，可選）：用於可重現生成的種子。

示例用法：

生成一個包含 20 個用戶和 100 個訂單的數據集，其中每個訂單引用一個用戶

示例請求（MCP 協議）：

{
  "method": "tools/call",
  "params": {
    "name": "generate-dataset",
    "arguments": {
      "schema": {
        "entities": {
          "users": {
            "count": 10,
            "type": "person",
            "fields": ["id", "fullName", "email", "phone"]
          },
          "orders": {
            "count": 30,
            "type": "custom",
            "fields": ["id", "userId", "productName", "price", "orderDate"],
            "relationships": {
              "userId": {
                "references": "users",
                "type": "one-to-many",
                "nullable": false
              }
            }
          }
        }
      },
      "locale": "en",
      "seed": 99999
    }
  }
}

示例輸出：

{
  "users": [
    {
      "id": "user_99999_0",
      "fullName": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+1-555-100-0001"
    },
    {
      "id": "user_99999_1",
      "fullName": "Jane Smith",
      "email": "jane.smith@example.com",
      "phone": "+1-555-100-0002"
    }
  ],
  "orders": [
    {
      "id": "order_99999_0",
      "userId": "user_99999_0",
      "productName": "Laptop",
      "price": 1299.99,
      "orderDate": "2024-03-15"
    },
    {
      "id": "order_99999_1",
      "userId": "user_99999_0",
      "productName": "Mouse",
      "price": 29.99,
      "orderDate": "2024-03-16"
    },
    {
      "id": "order_99999_2",
      "userId": "user_99999_1",
      "productName": "Keyboard",
      "price": 89.99,
      "orderDate": "2024-03-17"
    }
  ]
}

4. generate-custom

根據自定義模式（包括正則表達式模式、枚舉、格式和範圍）生成數據。 參數：

• count（數字，可選）：要生成的記錄數量（1 - 10,000，默認值：1）。
• patterns（對象，必需）：字段名稱到模式定義的映射。
  • type（字符串）：模式類型 - regex、enum、format 或 range。
  • value：模式值（取決於模式類型）：
    • regex：正則表達式字符串（例如，"PRD-[0-9]{4}-[A-Z]{2}"）。
    • enum：可供選擇的字符串值數組（例如，["pending", "active", "completed"]）。
    • format：帶有佔位符的模板字符串（例如，"REF-{{year}}-{{random:5}}"）。
    • range：包含 min 和 max 數值的對象（例如，{"min": 10, "max": 1000}）。
• locale（字符串，可選）：生成數據的語言環境 - 影響基於格式的模式（默認值：en）。
• seed（數字，可選）：用於可重現生成的種子。

示例用法：

生成 50 條產品記錄，其代碼符合模式 PRD - #### - XX，其中 # 是數字，X 是大寫字母

示例請求（MCP 協議）：

{
  "method": "tools/call",
  "params": {
    "name": "generate-custom",
    "arguments": {
      "count": 5,
      "patterns": {
        "productCode": {
          "type": "regex",
          "value": "PRD-[0-9]{4}-[A-Z]{2}"
        },
        "status": {
          "type": "enum",
          "value": ["pending", "active", "completed", "cancelled"]
        },
        "price": {
          "type": "range",
          "value": { "min": 10, "max": 1000 }
        },
        "reference": {
          "type": "format",
          "value": "REF-{{year}}-{{random:5}}"
        }
      },
      "locale": "en",
      "seed": 11111
    }
  }
}

示例輸出：

[
  {
    "id": "custom_11111_0",
    "productCode": "PRD-1234-AB",
    "status": "active",
    "price": 456.78,
    "reference": "REF-2024-A3B5C"
  },
  {
    "id": "custom_11111_1",
    "productCode": "PRD-5678-CD",
    "status": "pending",
    "price": 123.45,
    "reference": "REF-2024-D7E9F"
  }
]

常見用例

數據庫填充

生成逼真的測試數據以填充開發數據庫：

使用種子 100 生成一個包含 100 個用戶、500 個訂單和 1000 個訂單項的數據集，並確保它們之間的關係正確

API 集成測試

創建具有逼真數據結構的測試負載：

生成 20 個包含電子郵件、密碼和個人資料信息的用戶註冊負載

UI 演示數據

使用特定語言環境的數據構建演示環境：

為一個演示電子商務網站生成法語語言環境的數據：50 個帶有地址的客戶和 200 個訂單

性能測試

生成大量數據進行負載測試：

生成 10000 條個人記錄，用於對我的用戶導入 API 進行負載測試

最佳實踐

1. 使用種子實現可重現性

當你需要在不同環境中獲得一致的測試數據時，始終指定一個種子：

使用種子 12345 生成 100 個用戶

2. 選擇合適的語言環境

根據目標市場選擇合適的語言環境，以生成逼真的數據：

使用德語語言環境（de）生成 50 家公司

3. 批量處理大型請求

對於非常大的數據集，可以考慮分批生成：

使用種子 111 生成 3000 條記錄（第一批）
使用種子 222 生成 3000 條記錄（第二批）
使用種子 333 生成 3000 條記錄（第三批）

4. 謹慎定義關係

確保在生成子實體之前先生成父實體：

{
  "entities": {
    "users": { "count": 10, "type": "person" },
    "orders": { 
      "count": 50, 
      "type": "custom",
      "relationships": { 
        "userId": { "references": "users", "type": "one-to-many" } 
      }
    }
  }
}

性能預期

操作	記錄數量	預期時間	內存使用
生成個人記錄	100	<100ms	<5MB
生成個人記錄	1,000	<1s	<50MB
生成個人記錄	10,000	<10s	<100MB
生成公司記錄	100	<100ms	<5MB
生成數據集	總計 1,000 條	<2s	<50MB
生成自定義數據	1,000 條	<1s	<30MB

性能可能會因系統資源和模式複雜性而有所不同。

錯誤處理

服務器遵循 MCP 標準錯誤響應格式。常見錯誤包括：

參數無效（代碼：-32602）：

{
  "error": {
    "code": -32602,
    "message": "無效的 count 參數：必須在 1 到 10000 之間",
    "data": {
      "received": 50000,
      "max": 10000
    }
  }
}

不支持的語言環境（代碼：-32001）：

{
  "error": {
    "code": -32001,
    "message": "不支持的語言環境：zh。支持的語言環境：en、fr、de、es、ja",
    "data": {
      "received": "zh",
      "supported": ["en", "fr", "de", "es", "ja"]
    }
  }
}

模式驗證錯誤（代碼：-32602）：

{
  "error": {
    "code": -32602,
    "message": "無效的模式：在關係中檢測到循環依賴",
    "data": {
      "cycle": ["orders", "items", "orders"]
    }
  }
}

📚 詳細文檔

MCP 客戶端配置

Claude Desktop

Claude Desktop 是一款支持 MCP 服務器以擴展功能的 AI 助手應用程序。 配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

配置：

{
  "mcpServers": {
    "faker": {
      "command": "npx",
      "args": ["faker-mcp-server"]
    }
  }
}

替代方案（使用全局安裝的包）：

{
  "mcpServers": {
    "faker": {
      "command": "faker-mcp-server",
      "args": []
    }
  }
}

配置後：重啟 Claude Desktop。你可以通過詢問“有哪些 MCP 工具可用？”來驗證連接。

Cline（VS Code 擴展）

Cline 是一個 VS Code 擴展，它通過 MCP 支持將 AI 輔助直接集成到你的編輯器中。 設置步驟：

1. 從 VS Code 市場安裝 Cline 擴展。
2. 打開 VS Code 設置（JSON） - 按下 Cmd/Ctrl + Shift + P → “首選項：打開用戶設置（JSON）”。
3. 添加 MCP 服務器配置：

{
  "cline.mcpServers": {
    "faker": {
      "command": "npx",
      "args": ["faker-mcp-server"],
      "transport": "stdio"
    }
  }
}

替代方案（特定於工作區的配置）： 在你的項目中創建或編輯 .vscode/settings.json：

{
  "cline.mcpServers": {
    "faker": {
      "command": "npx",
      "args": ["faker-mcp-server"],
      "transport": "stdio"
    }
  }
}

配置後：重新加載 VS Code 窗口或重啟 Cline 擴展。

Continue（VS Code 擴展）

Continue 是一個支持 MCP 的開源 VS Code AI 代碼助手。 配置文件位置：~/.continue/config.json（或特定於工作區的 .continue/config.json）。 配置：

{
  "mcpServers": [
    {
      "name": "faker",
      "command": "npx",
      "args": ["faker-mcp-server"],
      "transport": "stdio"
    }
  ]
}

配置後：重啟 Continue 擴展或重新加載 VS Code。

Zed Editor

Zed 是一款內置 AI 和 MCP 支持的高性能代碼編輯器。 配置文件位置：~/.config/zed/settings.json。 配置：

{
  "context_servers": {
    "faker-mcp-server": {
      "command": "npx",
      "args": ["faker-mcp-server"]
    }
  }
}

配置後：重啟 Zed 編輯器。

MCP Inspector（開發/測試）

MCP Inspector 是一個用於在開發過程中測試 MCP 服務器的官方調試工具。 用法：

# 全局安裝 MCP Inspector
npm install -g @modelcontextprotocol/inspector

# 使用 Faker MCP 服務器運行
mcp-inspector npx faker-mcp-server

這將在 http://localhost:5173 打開一個 Web 界面，你可以在其中：

• 發現所有可用的工具。
• 使用自定義參數測試工具調用。
• 查看請求/響應日誌。
• 驗證 MCP 協議合規性。

自定義 MCP 客戶端（通用集成）

對於任何未列出的兼容 MCP 的客戶端，請使用以下配置參數： 連接參數：

• 命令：npx faker-mcp-server（如果全局安裝，也可以使用 faker-mcp-server）。
• 傳輸：stdio（標準輸入/輸出）。
• 協議：MCP（Model Context Protocol）。
• 環境：需要 Node.js 18 或更高版本。

通用 JSON 配置：

{
  "command": "npx",
  "args": ["faker-mcp-server"],
  "transport": "stdio",
  "env": {
    "NODE_ENV": "production"
  }
}

使用絕對路徑（當 npx 不可用時）：

{
  "command": "/usr/local/bin/faker-mcp-server",
  "args": [],
  "transport": "stdio"
}

使用自定義 Node 路徑：

{
  "command": "/usr/local/bin/node",
  "args": ["/path/to/node_modules/.bin/faker-mcp-server"],
  "transport": "stdio",
  "env": {
    "NODE_ENV": "production",
    "NODE_OPTIONS": "--max-old-space-size=512"
  }
}

Docker 容器

對於容器化環境或 CI/CD 管道： Dockerfile：

FROM node:18-alpine
RUN npm install -g faker-mcp-server
CMD ["faker-mcp-server"]

構建和運行：

docker build -t faker-mcp-server .
docker run -i faker-mcp-server

Docker Compose（用於與其他服務集成）：

version: '3.8'
services:
  faker-mcp:
    image: node:18-alpine
    command: npx faker-mcp-server
    stdin_open: true
    tty: true

編程式使用（Node.js）

你還可以在 Node.js 應用程序中以編程方式使用 MCP 服務器：

import { spawn } from 'child_process';

// 啟動 MCP 服務器進程
const mcpServer = spawn('npx', ['faker-mcp-server'], {
  stdio: ['pipe', 'pipe', 'inherit']
});

// 發送 MCP 請求以生成個人數據
const request = {
  jsonrpc: '2.0',
  id: 1,
  method: 'tools/call',
  params: {
    name: 'generate-person',
    arguments: {
      count: 5,
      locale: 'en',
      seed: 12345
    }
  }
};

mcpServer.stdin.write(JSON.stringify(request) + '\n');

// 讀取響應
mcpServer.stdout.on('data', (data) => {
  const response = JSON.parse(data.toString());
  console.log('生成的數據:', response.result);
});

配置故障排除

問題：“找不到命令：faker-mcp-server” 解決方案：

• 使用 npx faker-mcp-server 代替 faker-mcp-server。
• 先全局安裝：npm install -g faker-mcp-server。
• 使用二進制文件的絕對路徑。

問題：“MCP 服務器連接超時” 解決方案：

• 驗證是否安裝了 Node.js 18 或更高版本：node --version。
• 檢查服務器是否可以手動啟動：npx faker-mcp-server。
• 查看客戶端日誌以獲取具體錯誤消息。
• 確保沒有防火牆/防病毒軟件阻止 Node.js 進程。

問題：“來自服務器的無效 JSON 響應” 解決方案：

• 確保傳輸設置為 stdio（而不是 http 或 sse）。
• 檢查 Node.js 版本兼容性（需要 18 或更高版本）。
• 驗證沒有其他進程正在使用標準輸入/輸出流。

特定平臺注意事項

macOS：

• 配置文件通常位於 ~/Library/Application Support/。
• 使用 Homebrew 安裝 Node.js：brew install node@18。

Windows：

• 配置文件通常位於 %APPDATA%\ 或 %USERPROFILE%\.config\。
• 使用 nodejs.org 上的 Node.js 安裝程序或 nvm-windows。
• 在 JSON 路徑中使用正斜槓或轉義反斜槓。

Linux：

• 配置文件通常位於 ~/.config/。
• 使用 nvm 管理 Node.js 版本。
• 確保執行權限：chmod +x /path/to/faker-mcp-server。

故障排除

"MCP 服務器未找到"

原因：服務器未正確安裝或配置。 解決方案：

1. 驗證安裝：npm list -g faker-mcp-server。
2. 檢查 MCP 客戶端配置文件中的命令是否正確。
3. 配置更改後重啟 MCP 客戶端。

"無效的語言環境錯誤"

原因：請求的語言環境不受支持。 解決方案：使用支持的語言環境之一：en、fr、de、es、ja。

"大數據集請求超時"

原因：生成超過 5000 條記錄可能需要幾秒鐘。 解決方案：

• 使用較小的批量大小。
• 耐心等待（通常生成 10,000 條記錄需要不到 10 秒）。
• 如果仍然超時，請檢查內存限制。

"數據集中的引用完整性錯誤"

原因：模式以錯誤的順序定義關係或存在循環依賴。 解決方案：

• 在定義子實體之前先定義父實體。
• 避免循環引用。
• 在生成之前驗證模式。

開發

設置

# 克隆倉庫
git clone <repository-url>
cd faker-mcp

# 安裝依賴項
npm install

# 運行測試
npm test

# 構建項目
npm run build

# 以開發模式運行
npm run dev

腳本

• npm run build - 為生產環境構建項目。
• npm run dev - 以監視模式構建，用於開發。
• npm test - 運行一次測試。
• npm run test:watch - 以監視模式運行測試。
• npm run test:coverage - 運行測試並生成覆蓋率報告。
• npm run lint - 對代碼進行 lint 檢查。
• npm run lint:fix - 進行 lint 檢查並修復問題。
• npm run format - 使用 Prettier 格式化代碼。
• npm run typecheck - 進行類型檢查但不生成輸出。

📄 許可證

本項目採用 MIT 許可證。

作者

Funs Janssen

貢獻

歡迎貢獻代碼！請隨時提交拉取請求。