# UUID v7/v8 Generator

**MCP Tool:** `uuid_generator`  
**Tier:** Tier 2 — Differentiated  
**Category:** generators  
**Endpoint:** https://obfus.link/mcp  
**Price:** $0.015 / call  
**Verification:** ✓ TDD verified  

> Generate, decode, and analyze UUIDs with collision analysis and DDL

## Atomic Answer

UUID Generator produces v4, v7, and v8 UUIDs with monotonic sequence mode for sortable batches. Decode mode parses any UUID version and extracts embedded timestamps and clock sequences. Collision Analyzer calculates birthday-problem probability for any dataset size. Database Migration Helper outputs ready-to-paste DDL for PostgreSQL, MySQL, CockroachDB, DynamoDB, and SQLite.

## Description

Generates v4, v7, and v8 UUIDs with monotonic sequence mode and annotated decode. Decode mode parses any UUID version (v1-v8). Collision Analyzer calculates birthday-problem probability. Database Migration Helper outputs ready-to-paste DDL for PostgreSQL, MySQL, CockroachDB, DynamoDB, and SQLite.

## Agentic Reasoning

USE THIS WHEN: (1) You need time-ordered UUIDs (v7) for database primary keys to avoid index fragmentation and improve append-only insert performance. (2) You have an opaque UUID and need to identify version, variant, embedded timestamp, and byte-level malformation. (3) You are choosing between v4 and v7 for a known dataset size and want collision probability math plus database-specific DDL recommendations. DO NOT USE WHEN: any random ID format is acceptable and you do not need decode or analysis — call crypto.randomUUID() directly. OVER ALTERNATIVES: prefer over uuidjs (no v7 decode, no collision analysis, no DB migration DDL) and crypto.randomUUID (v4 only, no time-ordering, no decode).

## MCP Description

Generates, decodes, and analyzes UUIDs. USE WHEN: producing time-ordered UUIDs (v7) for database PKs, decoding an unknown UUID to identify version and embedded timestamps, or evaluating UUID strategy via collision probability and DDL recommendations. INPUT: mode plus mode-specific fields. OUTPUT: generated UUIDs (with optional timestamp annotations), decoded metadata, or collision analysis with DB migration DDL. COST: 1 unit.

## Input Schema

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `mode` | `generate` \| `decode` \| `analyze-collisions` | yes |  |
| `uuid` | `string` | no |  |
| `count` | `number` | no |  |
| `format` | `standard` \| `no-dashes` \| `braces` \| `urn` | no |  |
| `version` | `4` \| `7` \| `8` | no |  |
| `annotate` | `boolean` | no |  |
| `targetScale` | `number` | no |  |
| `sequenceMode` | `boolean` | no |  |
| `existingUuids` | `array` | no |  |
| `targetDatabase` | `postgresql` \| `mysql` \| `cockroachdb` \| `dynamodb` \| `sqlite` | no |  |

## Output Schema

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uuids` | `array` | no |  |
| `decoded` | `object` | no |  |
| `annotations` | `array` | no |  |
| `collisionAnalysis` | `object` | no |  |

## How To Use

1. **Choose mode** — generate (produce UUIDs), decode (parse a UUID), or analyze-collisions (calculate probability + DDL).
2. **Pick version** — v4 (random), v7 (time-ordered, recommended for DB PKs), or v8 (custom namespace).
3. **Set count** — How many UUIDs to generate (1-100). Combined with sequenceMode for strict monotonic ordering.
4. **Enable annotation (optional)** — Annotate decodes each generated v7 UUID back to its embedded timestamp.
5. **Decode or analyze** — Decode mode accepts any UUID. Collision mode accepts existing UUIDs and target scale for probability + DDL.

## FAQs

**Why use v7 instead of v4?**

v7 UUIDs embed a timestamp in the high bits, making them naturally sortable by creation time. This dramatically improves database insert performance on B-tree indexes (no random seeks) and enables time-range queries on the PK directly. v4 is purely random and causes index fragmentation in append-heavy workloads.

**What does Decode return for a v1 UUID?**

For v1 (and v6, v7): version, variant, embedded timestamp (with ms precision and ISO time), clock sequence, and node ID. Plus byte-level malformation checks. For v3, v4, v5, v8: only version, variant, and structural validation are returned.

**How does the birthday-problem collision probability work?**

For a random 122-bit UUID and N rows, the probability of at least one collision is approximately N^2 / (2 * 2^122). The analyzer computes this for your target scale and returns a human-readable form ("1 in 2.71 × 10^18"). For v7 the math is similar but the time-ordering reduces effective entropy slightly.

**What is monotonic sequence mode?**

When sequenceMode is true and you generate multiple UUIDs in the same call, the sequence bits increment within the same millisecond — guaranteeing strict sort order across the batch. Critical for databases that depend on UUID v7 sort order for query performance.

**Can I use this tool via the MCP API?**

Yes. The tool is registered on the obfus.link MCP server at https://obfus.link/mcp. Call it from any MCP-compatible agent with a Shared Payment Token. The MCP tool name matches the snake_case slug shown in the integration snippet.

## Tags

`uuid` · `id` · `generate` · `v7` · `v8` · `database`

---

*obfus.link — A Subether Labs Infrastructure Project*  
*Canonical URL: https://obfus.link/tool/uuid-generator*  
*JSON view: https://obfus.link/tool/uuid-generator/json*