# Directory Structure
```
├── .gitignore
├── claude_desktop_config_example.json
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
├── src
│ └── index.ts
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | # Dependency directories
2 | node_modules/
3 |
4 | # Build output
5 | build/
6 |
7 | # Environment variables
8 | .env
9 |
10 | # Logs
11 | logs
12 | *.log
13 | npm-debug.log*
14 | yarn-debug.log*
15 | yarn-error.log*
16 |
17 | # Editor directories and files
18 | .idea
19 | .vscode
20 | *.swp
21 | *.swo
22 |
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # UUID MCP Provider
2 |
3 | A simple Model Context Protocol (MCP) server that provides timestamp-based UUIDs whenever it's called by an LLM.
4 |
5 | ## Features
6 |
7 | - Provides a single tool: `generateUuid`
8 | - Uses UUID v7 for timestamp-based unique identifiers
9 | - Simple interface with no input parameters needed
10 | - Easy integration with Claude and other LLMs
11 |
12 | ## Installation
13 |
14 | ```bash
15 | # Install dependencies
16 | npm install
17 |
18 | # Build the project
19 | npm run build
20 | ```
21 |
22 | ## Usage
23 |
24 | You can run the server directly:
25 |
26 | ```bash
27 | npm start
28 | ```
29 |
30 | ### Integration with Claude Desktop
31 |
32 | To integrate with Claude Desktop, add this to your Claude Desktop configuration file:
33 |
34 | - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
35 | - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
36 |
37 | ```json
38 | {
39 | "mcpServers": {
40 | "uuid-provider": {
41 | "command": "node",
42 | "args": ["/absolute/path/to/uuid-mcp/build/index.js"]
43 | }
44 | }
45 | }
46 | ```
47 |
48 | Replace `/absolute/path/to/uuid-mcp/build/index.js` with the absolute path to your built index.js file.
49 |
50 | After updating the configuration, restart Claude Desktop to see the UUID generation tool available.
51 |
52 | ## How It Works
53 |
54 | This server uses the official `uuid` package to generate UUID v7 identifiers. UUID v7 is specifically designed to be timestamp-based while maintaining strong uniqueness guarantees:
55 |
56 | - Incorporates a Unix timestamp in millisecond precision
57 | - Adds randomized data to ensure uniqueness even when multiple IDs are generated in the same millisecond
58 | - Follows the latest RFC standards for UUID generation
59 | - Provides chronologically sortable identifiers
60 | - Prevents collisions in distributed systems
61 |
62 | This approach is more reliable than custom UUID implementations and eliminates the potential for duplicates even under high load.
63 |
64 | ## Dependencies
65 |
66 | - `@modelcontextprotocol/sdk`: For MCP server implementation
67 | - `uuid`: For RFC-compliant UUID generation
68 | - TypeScript and related tools for development
69 |
70 | ## Example
71 |
72 | When called, the tool returns a UUID v7 string that looks like:
73 |
74 | ```
75 | 018e94d2-279b-7bd3-9289-80d1e6619670
76 | ```
77 |
78 | The first part of the UUID contains the timestamp, making these identifiers chronologically sortable while still maintaining the standard UUID format.
79 |
```
--------------------------------------------------------------------------------
/claude_desktop_config_example.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "mcpServers": {
3 | "uuid-provider": {
4 | "command": "node",
5 | "args": ["/Users/ericwu/projects/doc/claude_working_dir/uuid-mcp/build/index.js"]
6 | }
7 | }
8 | }
9 |
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "compilerOptions": {
3 | "target": "ES2022",
4 | "module": "Node16",
5 | "moduleResolution": "Node16",
6 | "outDir": "./build",
7 | "esModuleInterop": true,
8 | "strict": true,
9 | "skipLibCheck": true,
10 | "forceConsistentCasingInFileNames": true
11 | },
12 | "include": ["src/**/*"],
13 | "exclude": ["node_modules"]
14 | }
15 |
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "uuid-mcp",
3 | "version": "1.0.0",
4 | "description": "A simple MCP server that provides timestamp-based UUIDs",
5 | "type": "module",
6 | "main": "build/index.js",
7 | "scripts": {
8 | "build": "tsc",
9 | "start": "node build/index.js"
10 | },
11 | "keywords": [
12 | "mcp",
13 | "uuid",
14 | "llm"
15 | ],
16 | "author": "",
17 | "license": "MIT",
18 | "dependencies": {
19 | "@modelcontextprotocol/sdk": "^1.8.0",
20 | "uuid": "^11.1.0"
21 | },
22 | "devDependencies": {
23 | "@types/node": "^22.13.17",
24 | "@types/uuid": "^10.0.0",
25 | "typescript": "^5.8.2"
26 | }
27 | }
28 |
```
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | // Import the required MCP modules
2 | import { Server } from "@modelcontextprotocol/sdk/server/index.js";
3 | import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
4 | import { v7 as uuidv7 } from 'uuid';
5 | import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
6 |
7 | // Create the server
8 | const server = new Server({
9 | name: "uuid-mcp-provider",
10 | version: "1.0.0"
11 | }, {
12 | capabilities: {
13 | tools: {} // We're only providing tools functionality
14 | }
15 | });
16 |
17 | // Register the tools/list endpoint to advertise our generateUuid tool
18 | server.setRequestHandler(
19 | ListToolsRequestSchema,
20 | async () => {
21 | return {
22 | tools: [
23 | {
24 | name: "generateUuid",
25 | description: "Generate a UUID v7 that's timestamp-based and guaranteed to be unique",
26 | inputSchema: {
27 | type: "object",
28 | properties: {}
29 | }
30 | }
31 | ]
32 | };
33 | }
34 | );
35 |
36 | // Register the tools/call endpoint to handle tool execution
37 | server.setRequestHandler(
38 | CallToolRequestSchema,
39 | async (request) => {
40 | if (request.params.name === "generateUuid") {
41 | // UUID v7 is timestamp-based with additional random data for uniqueness
42 | const uuid = uuidv7();
43 |
44 | return {
45 | content: [
46 | {
47 | type: "text",
48 | text: uuid
49 | }
50 | ]
51 | };
52 | }
53 |
54 | throw new Error(`Unknown tool: ${request.params.name}`);
55 | }
56 | );
57 |
58 | // Start the server
59 | async function main() {
60 | try {
61 | const transport = new StdioServerTransport();
62 | await server.connect(transport);
63 | console.error("UUID MCP Provider running on stdio...");
64 | } catch (error) {
65 | console.error("Error starting server:", error);
66 | process.exit(1);
67 | }
68 | }
69 |
70 | main();
71 |
```