# 🛠️ Local Utilities MCP Server

A comprehensive **Model Context Protocol (MCP)** server built with FastMCP that provides essential utility tools for text processing, file operations, system tasks, and more.

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.9.0+-green.svg)](https://pypi.org/project/fastmcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🌟 Features

### 🌡️ **Temperature Conversion**
- Convert between Celsius and Fahrenheit
- High precision calculations with 2 decimal places

### 📁 **File Operations**  
- **Read** text files with full content display
- **Write** content to files with automatic directory creation
- **List** directory contents with file sizes and icons

### 🔐 **Security & Hashing**
- Calculate **MD5**, **SHA1**, **SHA256** hashes
- Hash text strings or entire file contents
- **Base64** encoding and decoding

### 📊 **Text Analysis**
- Count words, characters, and lines
- Calculate detailed text statistics
- Average words per line and characters per word

### 🕒 **Date & Time**
- Get current date and time information
- Custom formatting with Python strftime
- Detailed breakdown (year, month, day, weekday, etc.)

### 🔑 **Password Generation**
- Generate secure passwords with customizable options
- Control length and character sets
- Include/exclude uppercase, lowercase, numbers, symbols

## 🚀 Quick Start

### Prerequisites

- Python 3.8 or higher
- Compatible MCP client (LM Studio, Claude Desktop, etc.)

### Installation

1. **Clone the repository:**
   ```bash
   git clone https://github.com/aiforhumans/local-utils-mcp.git
   cd local-utils-mcp
   ```

2. **Create and activate a virtual environment:**
   ```bash
   python -m venv .venv
   
   # Windows
   .venv\Scripts\activate
   
   # macOS/Linux
   source .venv/bin/activate
   ```

3. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

### Running the Server

**Start the MCP server:**
```bash
python server.py
```

The server runs on `stdio` transport by default, which is compatible with most MCP clients.

## 🔧 Configuration

### LM Studio Integration

Add this configuration to your LM Studio `mcp.json` file:

```json
{
  "mcpServers": {
    "local-utils": {
      "command": "python",
      "args": ["path/to/your/server.py"],
      "env": {}
    }
  }
}
```

### Claude Desktop Integration

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "local-utils": {
      "command": "python",
      "args": ["path/to/your/server.py"]
    }
  }
}
```

## 📖 API Reference

### Available Tools

#### `convert_temp(value: float, unit: str)`
Convert temperature between Celsius and Fahrenheit.

**Parameters:**
- `value`: Temperature value to convert
- `unit`: "C" for Celsius to Fahrenheit, "F" for Fahrenheit to Celsius

**Example:**
```
convert_temp(25, "C") → "77.00 °F"
convert_temp(77, "F") → "25.00 °C"
```

#### `read_file(file_path: str)`
Read and return the contents of a text file.

**Parameters:**
- `file_path`: Absolute or relative path to the file

**Returns:** File contents with path information

#### `write_file(file_path: str, content: str)`
Write content to a text file with automatic directory creation.

**Parameters:**
- `file_path`: Path where to write the file
- `content`: Text content to write

#### `list_directory(directory_path: str = ".")`
List contents of a directory with file sizes.

**Parameters:**
- `directory_path`: Path to directory (defaults to current directory)

**Returns:** Formatted list with file/folder icons and sizes

#### `calculate_hash(text_or_path: str, hash_type: str = "sha256", is_file: bool = False)`
Calculate cryptographic hash of text or file content.

**Parameters:**
- `text_or_path`: Text string or file path to hash
- `hash_type`: "md5", "sha1", or "sha256" (default)
- `is_file`: Set to `true` when hashing a file

#### `base64_encode_decode(text: str, operation: str = "encode")`
Encode or decode text using Base64.

**Parameters:**
- `text`: Text to encode/decode
- `operation`: "encode" or "decode"

#### `get_datetime_info(format_string: str = "%Y-%m-%d %H:%M:%S")`
Get comprehensive current date and time information.

**Parameters:**
- `format_string`: Python strftime format string for custom formatting

#### `text_stats(text: str)`
Calculate detailed statistics for the given text.

**Parameters:**
- `text`: Text to analyze

**Returns:** Lines, words, characters, and averages

#### `generate_password(length: int = 12, include_uppercase: bool = True, include_lowercase: bool = True, include_numbers: bool = True, include_symbols: bool = False)`
Generate a secure random password.

**Parameters:**
- `length`: Password length (default: 12)
- `include_uppercase`: Include A-Z (default: true)
- `include_lowercase`: Include a-z (default: true)  
- `include_numbers`: Include 0-9 (default: true)
- `include_symbols`: Include special characters (default: false)

## 🧪 Testing

Run the test suite to verify functionality:

```bash
python test.py
```

This will test all core functions and verify the server can be imported correctly.

## 🔨 Development

### Adding New Tools

To extend the server with additional tools:

1. **Create a new function** with the `@mcp.tool()` decorator:

```python
@mcp.tool(
    description="Your tool description here"
)
async def your_new_tool(param1: str, param2: int = 10) -> str:
    """
    Your tool implementation.
    
    Args:
        param1: Description of parameter 1
        param2: Description of parameter 2 with default value
    
    Returns:
        String result of the tool operation
    """
    try:
        # Your tool logic here
        result = f"Processed {param1} with value {param2}"
        return result
    except Exception as e:
        return f"Error: {str(e)}"
```

2. **Add proper error handling** and meaningful return messages
3. **Update the README** with documentation for your new tool
4. **Test your tool** to ensure it works correctly

### Project Structure

```
local-utils-mcp/
├── server.py              # Main MCP server
├── requirements.txt       # Python dependencies  
├── README.md             # This file
├── .gitignore           # Git ignore rules
├── test.py              # Test suite
└── .venv/               # Virtual environment (not in git)
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📋 Requirements

- Python 3.8+
- FastMCP 2.9.0+
- MCP 1.9.4+

See `requirements.txt` for complete dependency list.

## 📄 License

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

## 🔗 Related Projects

- [FastMCP](https://github.com/jlowin/fastmcp) - The FastMCP framework used to build this server
- [Model Context Protocol](https://modelcontextprotocol.io/) - Official MCP documentation
- [LM Studio](https://lmstudio.ai/) - Popular MCP client for local AI models

## ⭐ Support

If you find this project helpful, please consider giving it a star on GitHub!

---

**Made with ❤️ for the MCP community**