# Softalleys Utilities MCP Server

A Model Context Protocol (MCP) server that provides utility tools for UUID generation, ULID generation, conversion between formats, UTC time retrieval, and random string generation.

## Features

This MCP server provides the following tools:

### UUID Tools
- **generate_uuid**: Generate a random UUID (version 4)
- **generate_uuid_v7**: Generate a time-based UUID (version 7) with optional datetime parameter
- **uuid_to_ulid**: Convert a UUID v7 to a ULID

### ULID Tools
- **generate_ulid**: Generate a time-based ULID with optional datetime parameter
- **ulid_to_uuid**: Convert a ULID to a UUID v7

### Time Tools
- **current_utc**: Get the current time in UTC (ISO 8601 format)

### Random String Tools
- **generate_random_string**: Generate a random string with customizable options:
  - Length (default: 10)
  - Include uppercase letters (default: true)
  - Include numbers (default: true)
  - Include special characters (default: true)

## Installation

### Using npm

```bash
npm install -g softalleys-utilities-mcp
```

### Using npx (no installation required)

```bash
npx softalleys-utilities-mcp
```

### Building from source

```bash
git clone <repository-url>
cd softalleys-utilities-mcp
npm install
npm run build
```

## Usage

### With Claude Desktop

Add this server to your Claude Desktop configuration file:

**macOS/Linux**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "softalleys-utilities": {
      "command": "npx",
      "args": ["-y", "softalleys-utilities-mcp"]
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "softalleys-utilities": {
      "command": "softalleys-utilities-mcp"
    }
  }
}
```

### With Docker

#### Build the Docker image

```bash
docker build -t softalleys-utilities-mcp .
```

#### Run with Docker

```bash
docker run -i softalleys-utilities-mcp
```

#### Use with Claude Desktop (Docker)

Add this to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "softalleys-utilities": {
      "command": "docker",
      "args": ["run", "-i", "softalleys-utilities-mcp"]
    }
  }
}
```

## Tool Examples

### Generate UUID v4
```
Request: Use the generate_uuid tool
Response: "550e8400-e29b-41d4-a716-446655440000"
```

### Generate UUID v7 with specific datetime
```
Request: Use generate_uuid_v7 with datetime "2024-01-15T10:30:00Z"
Response: "018d2e4a-7a00-7000-8000-000000000000"
```

### Generate ULID
```
Request: Use generate_ulid
Response: "01HJ8X4Y9Z6M2K3N4P5Q6R7S8T"
```

### Convert UUID v7 to ULID
```
Request: Use uuid_to_ulid with uuid "018d2e4a-7a00-7000-8000-000000000000"
Response: "01HJ8X4Y9Z6M2K3N4P5Q6R7S8T"
```

### Get current UTC time
```
Request: Use current_utc
Response: "2024-10-29T16:45:30.123Z"
```

### Generate random string
```
Request: Use generate_random_string with length 16, includeUpperCase true, includeNumbers true, includeSpecialChars false
Response: "aB3dE5fG7hI9jK1l"
```

## Development

### Prerequisites
- Node.js 20 or higher
- npm

### Setup
```bash
npm install
```

### Build
```bash
npm run build
```

### Watch mode
```bash
npm run watch
```

## Technical Details

- Built with TypeScript
- Uses the Model Context Protocol SDK
- UUID generation via the `uuid` package
- ULID generation via the `ulidx` package
- Follows MCP specification for tool registration and execution

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.