UUID Generator Actor with MCP Server

A comprehensive UUID toolkit for the Apify platform with Model Context Protocol (MCP) server integration. Generate, validate, analyze, and manage universally unique identifiers (UUIDs) with support for multiple UUID versions and advanced operations.

Features

Core Operations

1. Generate - Create UUIDs in bulk with multiple version support
2. Validate - Check if a UUID is valid and identify its version
3. Analyze - Extract detailed information from UUIDs (version, variant, timestamp, format)
4. Convert - Transform UUIDs between different formats
5. Batch Validate - Validate multiple UUIDs at once
6. Batch Analyze - Analyze multiple UUIDs with statistics
7. Check Collisions - Find duplicate UUIDs in collections
8. Statistics - Generate comprehensive UUID statistics

UUID Version Support

• Version 1 (v1): Timestamp-based UUIDs with MAC address
• Version 4 (v4): Random UUIDs (most common)
• Version 5 (v5): Namespace-based UUIDs using SHA-1

Output Formats

• JSON: Structured data with full metadata support
• CSV: Comma-separated values for database imports
• Plain Text: One UUID per line for simple integration

MCP Server Integration

Built-in Model Context Protocol server for AI agent integration. Allows AI assistants (like Claude, GPT, etc.) to directly access UUID operations as tools.

Quick Start

As an Apify Actor

const { ApifyClient } = require('apify-client');

const client = new ApifyClient({ token: 'YOUR_API_TOKEN' });

const run = await client.actor('YOUR_ACTOR_ID').call({
    operation: 'generate',
    uuidVersion: 'v4',
    count: 100,
    outputFormat: 'json',
});

As an MCP Server

Configure in your MCP settings:

{
  "mcpServers": {
    "uuid-generator": {
      "command": "npx",
      "args": ["-y", "uuid-generator-actor", "mcp"]
    }
  }
}

Operations

1. Generate UUIDs

Create UUIDs in bulk with specified version and formatting options.

Input:

{
  "operation": "generate",
  "uuidVersion": "v4",
  "count": 10,
  "outputFormat": "json",
  "includeMetadata": true,
  "uppercase": false,
  "removeDashes": false
}

Output:

[
  {
    "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "version": "v4",
    "timestamp": "2025-11-06T10:30:00.000Z",
    "format": "standard"
  }
]

2. Validate UUID

Check if a UUID is valid and get its version.

Input:

{
  "operation": "validate",
  "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "outputFormat": "json"
}

Output:

{
  "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "valid": true,
  "version": 4,
  "message": "Valid UUID version 4"
}

3. Analyze UUID

Extract detailed information including version, variant, format, and timestamp (for v1).

Input:

{
  "operation": "analyze",
  "uuid": "6fa459ea-ee8a-11ed-a05b-0242ac120003",
  "outputFormat": "json"
}

Output:

{
  "valid": true,
  "uuid": "6fa459ea-ee8a-11ed-a05b-0242ac120003",
  "version": 1,
  "format": "standard",
  "variant": "RFC 4122",
  "type": "timestamp-based",
  "timestamp": {
    "iso": "2023-04-20T15:30:42.000Z",
    "unix": 1682005842000,
    "raw": "138967806420000000"
  }
}

4. Convert Format

Transform UUIDs between different formats (standard/compact, upper/lowercase).

Input:

{
  "operation": "convert",
  "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "uppercase": true,
  "removeDashes": true,
  "outputFormat": "json"
}

Output:

{
  "original": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "converted": "F47AC10B58CC4372A5670E02B2C3D479",
  "options": {
    "uppercase": true,
    "removeDashes": true
  }
}

5. Batch Validate

Validate multiple UUIDs at once.

Input:

{
  "operation": "batch_validate",
  "uuids": [
    "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "invalid-uuid",
    "8b3e8f7a-5d9c-4b2a-9f1e-6d8c7b5a4e3d"
  ],
  "outputFormat": "json"
}

Output:

{
  "total": 3,
  "valid": 2,
  "invalid": 1,
  "results": [
    {
      "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "valid": true,
      "version": 4
    },
    {
      "uuid": "invalid-uuid",
      "valid": false,
      "version": null
    },
    {
      "uuid": "8b3e8f7a-5d9c-4b2a-9f1e-6d8c7b5a4e3d",
      "valid": true,
      "version": 4
    }
  ]
}

6. Batch Analyze

Analyze multiple UUIDs with version breakdown.

Input:

{
  "operation": "batch_analyze",
  "uuids": [
    "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "6fa459ea-ee8a-11ed-a05b-0242ac120003"
  ],
  "outputFormat": "json"
}

Output:

{
  "total": 2,
  "valid": 2,
  "invalid": 0,
  "versionBreakdown": {
    "1": 1,
    "4": 1
  },
  "results": [...]
}

7. Check Collisions

Find duplicate UUIDs in a collection.

Input:

{
  "operation": "check_collisions",
  "uuids": [
    "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "8b3e8f7a-5d9c-4b2a-9f1e-6d8c7b5a4e3d",
    "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  ],
  "outputFormat": "json"
}

Output:

{
  "total": 3,
  "unique": 2,
  "duplicates": 1,
  "collisions": [
    {
      "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "index": 2
    }
  ]
}

8. Generate Statistics

Get comprehensive statistics about UUID collections.

Input:

{
  "operation": "statistics",
  "uuids": [
    "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "6fa459ea-ee8a-11ed-a05b-0242ac120003",
    "cfbff0d1-9375-5685-968c-48ce8b15ae17"
  ],
  "outputFormat": "json"
}

Output:

{
  "total": 3,
  "versions": {
    "1": 1,
    "4": 1,
    "5": 1
  },
  "formats": {
    "standard": 3,
    "compact": 0
  },
  "variants": {
    "RFC 4122": 3
  }
}

MCP Server Tools

When running as an MCP server, the following tools are available to AI agents:

• generate_uuid - Generate UUIDs with version and format options
• validate_uuid - Validate a single UUID
• analyze_uuid - Analyze UUID and extract details
• convert_uuid_format - Convert UUID format
• batch_validate - Validate multiple UUIDs
• batch_analyze - Analyze multiple UUIDs
• check_collisions - Find duplicates
• generate_statistics - Generate UUID statistics

MCP Server Usage

Start the MCP server:

$npm run mcp

Or install globally and run:

npm install -g uuid-generator-actor
uuid-generator-mcp

Configuration

Input Schema

Field	Type	Default	Description
operation	String	generate	Operation to perform
uuidVersion	String	v4	UUID version (v1, v4, v5)
count	Integer	10	Number of UUIDs to generate (1-100,000)
namespace	String	DNS	Namespace for v5 (DNS, URL, OID, X500, or custom)
name	String	-	Name for v5 hashing (required for v5)
uuid	String	-	Single UUID for validate/analyze/convert
uuids	Array	-	Multiple UUIDs for batch operations
outputFormat	String	json	Output format (json, csv, text)
includeMetadata	Boolean	true	Include metadata in JSON output
uppercase	Boolean	false	Output in uppercase
removeDashes	Boolean	false	Remove dashes (compact format)

Predefined Namespaces (UUID v5)

• DNS - For domain names (6ba7b810-9dad-11d1-80b4-00c04fd430c8)
• URL - For URLs (6ba7b811-9dad-11d1-80b4-00c04fd430c8)
• OID - For ISO OIDs (6ba7b812-9dad-11d1-80b4-00c04fd430c8)
• X500 - For X.500 DNs (6ba7b814-9dad-11d1-80b4-00c04fd430c8)

Use Cases

Software Development

• Generate unique IDs for database records
• Create session tokens
• Generate unique filenames
• API key generation

Testing & QA

• Generate test data with unique identifiers
• Validate UUID fields in APIs
• Test UUID collision resistance
• Performance testing with bulk UUID generation

Data Management

• Database record identification
• Distributed system node IDs
• File versioning systems
• Message queue identifiers

Analysis & Auditing

• Validate UUID compliance in datasets
• Analyze UUID version distribution
• Detect duplicate identifiers
• Generate UUID usage reports

API Integration

Using Apify Client

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

// Generate UUIDs
const generateRun = await client.actor('YOUR_ACTOR_ID').call({
  operation: 'generate',
  uuidVersion: 'v4',
  count: 1000,
  outputFormat: 'json'
});

const dataset = await client.dataset(generateRun.defaultDatasetId).listItems();
console.log(dataset.items);

Using Apify SDK

import { Actor } from 'apify';

// Call the UUID Generator Actor
const run = await Actor.call('YOUR_ACTOR_ID', {
  operation: 'validate',
  uuid: 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
});

// Get results
const { items } = await Actor.openDataset(run.defaultDatasetId).getData();
console.log(items[0]);

Performance

• Generation: Up to 100,000 UUIDs per run
• Validation: Handles large batches efficiently
• Memory: Optimized for minimal memory footprint
• Progress Logging: Real-time updates for batches > 1,000 items

Best Practices

1. Use UUID v4 for general purposes - Random UUIDs are suitable for most use cases
2. Use UUID v5 for deterministic generation - When you need the same input to produce the same UUID
3. Use UUID v1 for sortable identifiers - When time-ordering is important
4. Batch operations for efficiency - Process multiple UUIDs in a single run
5. Choose appropriate output format:
   • JSON for metadata and structured data
   • CSV for database imports
   • Text for simple scripts and piping

RFC 4122 Compliance

This Actor follows RFC 4122 standards:

• Correct version bits in all generated UUIDs
• Proper variant field encoding
• Standard formatting (8-4-4-4-12 hex digits)
• Cryptographically secure random generation for v4

Error Handling

The Actor includes comprehensive error handling:

• Input validation with clear error messages
• UUID format validation
• Version-specific requirement checks
• Graceful handling of invalid inputs

Installation

Local Installation

git clone https://github.com/Yash-Kavaiya/uuid-generator-actor-mcp.git
cd uuid-generator-actor-mcp
npm install

Running Locally

# As Apify Actor
npm start

# As MCP Server
npm run mcp

Examples

See the .actor/input_examples/ directory for complete example configurations for all operations.

Support & Contribution

• Report Issues: GitHub Issues
• Contribute: Pull requests welcome
• Documentation: Full API Documentation

License

Apache-2.0

Keywords

uuid, guid, identifier, generator, apify, actor, mcp, model-context-protocol, validation, analysis, batch-operations, unique-id, v1, v4, v5, random, timestamp, namespace, collision-detection

---

Production Ready - This Actor follows Apify best practices and is designed for reliability, scalability, and easy integration with your existing workflows and AI agents.