# mcp-devutils

A production-ready MCP (Model Context Protocol) server providing essential utility functions for AI development workflows.

## Features

- **UUID v4 Generation**: Generate random UUIDs
- **Base64 Encoding/Decoding**: Encode and decode text to/from Base64 format
- **Timestamp Conversion**: Convert between Unix timestamps and human-readable datetime strings
- **Hash Computation**: Compute MD5 and SHA256 hashes of text strings

## Requirements

- Python >= 3.10

## Installation

### From PyPI

```bash
pip install mcp-devutils
```

### Add to Claude Desktop

```bash
claude mcp add "mcp-devutils" --command "mcp-devutils"
```

### From Source

```bash
git clone https://github.com/yourusername/mcp-devutils.git
cd mcp-devutils
pip install -e .
```

## Usage

### Running the Server

You can run the MCP server using either the command-line script or directly with Python:

**Using the command-line script:**

```bash
mcp-devutils
```

**Using Python directly:**

```bash
python -m mcp_devutils.server
```

**Running from source directory:**

```bash
python src/mcp_devutils/server.py
```

## Tools

| Tool | Description |
|------|-------------|
| `generate_uuid` | Generate a random UUID v4 |
| `base64_encode` | Encode text to Base64 format |
| `base64_decode` | Decode Base64 to text |
| `timestamp_to_datetime` | Convert Unix timestamp to human-readable datetime |
| `datetime_to_timestamp` | Convert datetime to Unix timestamp |
| `md5_hash` | Compute MD5 hash of text |
| `sha256_hash` | Compute SHA256 hash of text |

### `generate_uuid`

Generate a random UUID v4.

**Returns:**
- `str`: A UUID v4 string (e.g., `123e4567-e89b-12d3-a456-426614174000`)

### `base64_encode`

Encode text to Base64 format.

**Parameters:**
- `text` (`str`): The text to encode

**Returns:**
- `str`: The Base64 encoded string

### `base64_decode`

Decode Base64 to text.

**Parameters:**
- `encoded_text` (`str`): The Base64 encoded text to decode

**Returns:**
- `str`: The decoded text string

### `timestamp_to_datetime`

Convert Unix timestamp to human-readable datetime.

**Parameters:**
- `timestamp` (`float`): Unix timestamp in seconds

**Returns:**
- `str`: Datetime string in ISO 8601 format (UTC)

### `datetime_to_timestamp`

Convert datetime to Unix timestamp.

**Parameters:**
- `datetime_str` (`str`): Datetime string in ISO 8601 format (e.g., `2024-01-01T12:00:00Z`)

**Returns:**
- `float`: Unix timestamp in seconds

### `md5_hash`

Compute MD5 hash of text.

**Parameters:**
- `text` (`str`): The text to hash

**Returns:**
- `str`: MD5 hash as hexadecimal string

### `sha256_hash`

Compute SHA256 hash of text.

**Parameters:**
- `text` (`str`): The text to hash

**Returns:**
- `str`: SHA256 hash as hexadecimal string

## Client Configuration

### Claude Desktop

1. Open Claude Desktop
2. Go to Settings → Model Context Protocol (MCP)
3. Click "Add Server"
4. Select "Command" as the connection type
5. Enter the command:
   ```
   mcp-devutils
   ```
6. Click "Connect"

### Cursor

1. Open Cursor
2. Open Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`)
3. Select "MCP: Add Server"
4. Choose "Command" from the dropdown
5. Enter the command:
   ```
   mcp-devutils
   ```
6. Click "OK"

### Manual Configuration (JSON)

You can also configure MCP clients using a JSON configuration file:

```json
{
  "name": "mcp-devutils",
  "command": "mcp-devutils",
  "type": "stdio"
}
```

## PyPI Publishing

### Prerequisites

- Install build tools:
  ```bash
  pip install build twine
  ```

### Build the Package

```bash
python -m build
```

This creates a `dist/` directory with `.tar.gz` and `.whl` files.

### Upload to PyPI

```bash
twine upload dist/*
```

You'll be prompted for your PyPI username and password.

### Upload to TestPyPI (for testing)

```bash
twine upload --repository testpypi dist/*
```

## Development

### Run Tests

```bash
pip install pytest
pytest
```

### Lint

```bash
pip install mypy
mypy src/
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.