Faker MCP

🚀 Faker MCP Server

Faker MCP Serverは、Faker.jsライブラリを使用して、擬似データを生成する機能を備えたModel Context Protocol (MCP) サーバーです。データベースのシーディング、APIテスト、デモアプリケーション、開発環境などで、現実的なテストデータを生成することができます。

このブログ記事で、なぜこのMCPサーバーを使用するのか、いつ使用するのかについて詳しく読むことができます。

✨ 主な機能

• 基本的なデータ生成：名前、メールアドレス、住所、連絡先情報など、現実的な人物や会社のデータを生成します。
• 構造化されたデータセット：複雑なテストシナリオに対応するため、参照整合性を持った複数のエンティティからなるデータセットを作成します。
• カスタムパターン：正規表現、列挙型、フォーマット、範囲などのカスタムパターンに従ってデータを生成し、特定のドメインの要件に対応します。
• 多言語サポート：英語、フランス語、ドイツ語、スペイン語、日本語などの複数の言語でデータを生成します。
• 再現可能なデータ：シードを指定することで、一貫したテストデータを生成します。
• 高性能：1秒間に1000件以上のレコードを生成することができます。
• MCPプロトコル準拠：MCP互換のクライアントとシームレスに統合することができます。

📦 インストール

前提条件

• システムにNode.js 18以上がインストールされていること。
• MCP互換のクライアント（例：Claude Desktop、Cline、CursorなどのMCPクライアント）が必要です。

🚀 クイックスタート

mcpServersセクションにFaker MCPサーバーを追加します。

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

様々なMCPクライアントの詳細なセットアップ手順については、MCPクライアントの設定セクションを参照してください。

💻 使用例

Faker MCP Serverは、擬似データを生成するための4つの強力なツールを提供しています。

基本的な使用法

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)

使用例:

再現性のためにシード54321を使用して、5つの会社レコードを生成する

リクエスト例 (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 (ブール値, オプション): 外部キーがnullになることができるかどうか (デフォルト: 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件の注文

パフォーマンステスト

負荷テストのために大量のデータを生成します。

ユーザーインポートAPIの負荷テストのために、10000人分の人物レコードを生成する

ベストプラクティス

1. 再現性のためにシードを使用する

環境を問わず一貫したテストデータが必要な場合は、常にシードを指定します。

シード12345を使用して、100人のユーザーを生成する

2. 適切なロケールを選択する

現実的なデータを得るために、ターゲット市場に合ったロケールを選択します。

ドイツ語のロケール (de) で50社の会社を生成する

3. 大規模なリクエストをバッチ処理する

非常に大きなデータセットの場合は、バッチで生成することを検討します。

シード111を使用して3000件のレコードを生成する (最初のバッチ)
シード222を使用して3000件のレコードを生成する (2番目のバッチ)
シード333を使用して3000件のレコードを生成する (3番目のバッチ)

4. 関係を慎重に定義する

子エンティティを生成する前に、親エンティティが生成されるようにします。

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

パフォーマンスの期待値

パフォーマンスは、システムリソースとパターンの複雑さによって異なります。

エラーハンドリング

サーバーは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は、MCPをサポートするVS Code拡張機能で、エディター内に直接AIアシスタントを提供します。

セットアップ手順:

1. VS Code MarketplaceからCline拡張機能をインストールします。
2. VS Codeの設定 (JSON) を開きます - Cmd/Ctrl + Shift + P を押して、「Preferences: Open User Settings (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インスペクター (開発/テスト)

MCPインスペクターは、開発中にMCPサーバーをテストするための公式のデバッグツールです。

使用方法:

# MCPインスペクターをグローバルにインストールする
npm install -g @modelcontextprotocol/inspector

# Faker MCPサーバーとともに実行する
mcp-inspector npx faker-mcp-server

これにより、http://localhost:5173 でウェブインターフェイスが開き、以下のことができます。

• 利用可能なすべてのツールを確認する
• カスタムパラメーターでツールの呼び出しをテストする
• リクエスト/レスポンスのログを表示する
• 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);
});

設定のトラブルシューティング

問題: "Command not found: faker-mcp-server"

解決策:

• faker-mcp-server の代わりに npx faker-mcp-server を使用します。
• 最初にグローバルにインストールします: npm install -g faker-mcp-server
• バイナリへの絶対パスを使用します。

問題: "MCP server connection timeout"

解決策:

• Node.js 18以上がインストールされていることを確認します: node --version
• サーバーが手動で起動するかどうかを確認します: npx faker-mcp-server
• クライアントのログを確認して、具体的なエラーメッセージを確認します。
• ファイアウォール/ウイルス対策ソフトがNode.jsプロセスをブロックしていないことを確認します。

問題: "Invalid JSON response from server"

解決策:

• トランスポートが stdio に設定されていることを確認します ( http や sse ではなく)。
• Node.jsのバージョン互換性を確認します (18以上が必要)。
• 他のプロセスがstdioストリームを使用していないことを確認します。

プラットフォーム固有の注意事項

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 server not found"

原因: サーバーが正しくインストールまたは設定されていない。

解決策:

1. インストールを確認します: npm list -g faker-mcp-server
2. MCPクライアントの設定ファイルで、正しいコマンドが指定されていることを確認します。
3. 設定を変更した後、MCPクライアントを再起動します。

"Invalid locale error"

原因: 要求されたロケールがサポートされていない。

解決策: サポートされているロケールのいずれかを使用します: en, fr, de, es, ja

"Request timeout for large datasets"

原因: 5000件以上のレコードを生成するには数秒かかる場合があります。

解決策:

• 小さいバッチサイズを使用します。
• 少々待つ必要があります (10,000件のレコードを生成するのに通常10秒未満かかります)。
• タイムアウトが繰り返される場合は、メモリ制限を確認します。

"Referential integrity errors in dataset"

原因: スキーマで関係が誤った順序で定義されているか、循環依存がある。

解決策:

• 子エンティティを生成する前に、親エンティティを定義します。
• 循環参照を避けます。
• 生成前にスキーマを検証します。

🔧 開発

セットアップ

# リポジトリをクローンする
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 - テストを1回実行する
• npm run test:watch - ウォッチモードでテストを実行する
• npm run test:coverage - カバレッジレポート付きでテストを実行する
• npm run lint - コードをリントする
• npm run lint:fix - リントして問題を修正する
• npm run format - Prettierでコードをフォーマットする
• npm run typecheck - 出力せずに型チェックする

📄 ライセンス

MIT

作者

Funs Janssen

コントリビューション

コントリビューションは大歓迎です！プルリクエストを送信してください。