# MCP Utility Kit

[![PyPI version](https://badge.fury.io/py/mcp-utility-kit.svg)](https://pypi.org/project/mcp-utility-kit/)
[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An MCP (Model Context Protocol) server built with FastMCP that provides three useful daily utility tools:
## Tools Provided

1. **Random Joke** - Get a random joke of the day
2. **Weather Data** - Get current weather using latitude and longitude
3. **Age Prediction** - Predict age based on a person's name

## Features

- 🎭 Daily jokes from the Official Joke API
- 🌤️ Real-time weather data from Open-Meteo
- 👤 Name-based age prediction from Agify
- 🚀 Fast and lightweight MCP server
- 📦 Published on PyPI - ready to use
- ⚡ No installation needed with `uvx`

## Quick Start

No installation or cloning required! Just add to your MCP configuration and start using.

### Prerequisites

- [uv](https://docs.astral.sh/uv/) package manager

Install uv:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

## Installation & Setup

### Quick Command (Claude CLI)

If you have the Claude CLI installed, add the server with one command:

```bash
claude mcp add daily-utils uvx mcp-utility-kit
```

### Option 1: Direct Use with uvx (Recommended)

Use directly without installation:

Add this configuration to your MCP settings file:

**VSCode**: `~/Library/Application Support/Code/User/mcp.json` (Mac) or `%APPDATA%\Code\User\mcp.json` (Windows)

**Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac)

```json
{
  "mcpServers": {
    "daily-utils": {
      "command": "uvx",
      "args": ["mcp-utility-kit"],
      "type": "stdio"
    }
  }
}
```

Then reload your MCP client:
- **VSCode**: Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows) → "Developer: Reload Window"
- **Claude Desktop**: Restart the application

That's it! The server will automatically download and run.

### Option 2: Install via pip

If you prefer traditional installation:

```bash
pip install mcp-utility-kit
```

Then run directly:
```bash
python -m mcp_utility_kit
```

### Option 3: Local Development Setup

For contributing or modifying the code:

1. Clone the repository:
```bash
git clone https://github.com/thananauto/mcp-utility-kit.git
cd mcp-utility-kit
```

2. Install dependencies:
```bash
uv sync
```

3. Use local configuration in `mcp.json`:
```json
{
  "mcpServers": {
    "daily-utils": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/full/path/to/mcp-utility-kit",
        "python",
        "-m",
        "mcp_utility_kit"
      ],
      "type": "stdio"
    }
  }
}
```

Replace `/full/path/to/mcp-utility-kit` with your local clone path

## Usage

Once configured in your MCP client, you can use these tools through your AI assistant:

- **"Tell me a joke"** - Gets a random joke
- **"What's the weather in New York?"** (provide latitude: 40.7128, longitude: -74.0060)
- **"Predict the age for the name Michael"**

### Running Standalone in Terminal

```bash
# Run directly with uvx (no install needed)
uvx mcp-utility-kit

# Or if installed via pip
python -m mcp_utility_kit

# From local development
uv run python -m mcp_utility_kit
```

### Testing with MCP Inspector

The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) provides a web UI for testing:

```bash
# Test published version
npx @modelcontextprotocol/inspector uvx mcp-utility-kit

# Test local version
npx @modelcontextprotocol/inspector uv run python -m mcp_utility_kit
```

This opens a browser interface where you can test all tools interactively.

### Available Tools

#### 1. get_joke_of_the_day()

Gets a random joke from the Official Joke API.

**Returns:** A formatted joke with setup and punchline

**Example:**
```
Why did the chicken cross the road?
To get to the other side!
```

#### 2. get_weather(latitude: float, longitude: float)

Gets current weather data for a location.

**Parameters:**
- `latitude` - Latitude of the location (e.g., 52.52 for Berlin)
- `longitude` - Longitude of the location (e.g., 13.41 for Berlin)

**Returns:** Formatted weather summary with temperature, wind speed, humidity, and weather code

**Example:**
```python
get_weather(latitude=40.7128, longitude=-74.0060)  # New York City
```

#### 3. predict_age_by_name(name: str)

Predicts the age associated with a given name using the Agify API.

**Parameters:**
- `name` - First name to predict age for (e.g., "Michael", "Sarah")

**Returns:** Predicted age and confidence count

**Example:**
```python
predict_age_by_name(name="Michael")
```

## APIs Used

This server integrates with the following free APIs:

- [Official Joke API](https://official-joke-api.appspot.com/) - Random jokes
- [Open-Meteo Weather API](https://open-meteo.com/) - Weather data (no API key required)
- [Agify Age Prediction API](https://agify.io/) - Name-based age prediction

## Updating the Package

This package is published on PyPI at: https://pypi.org/project/mcp-utility-kit/

### Publishing Updates

To publish a new version:

1. **Update version** in [pyproject.toml](pyproject.toml):
```toml
version = "0.2.0"  # Increment version number
```

2. **Build the package**:
```bash
uv build
```

3. **Install publishing tools** (if not already installed):
```bash
uv pip install twine
```

4. **Upload to PyPI**:
```bash
uv run twine upload -u __token__ -p YOUR_PYPI_TOKEN dist/*
```

Get your PyPI token from: https://pypi.org/manage/account/token/

### Test Before Publishing

Test on Test PyPI first (optional):
```bash
uv run twine upload --repository testpypi -u __token__ -p YOUR_TEST_TOKEN dist/*
```

## Sharing with Team Members

Team members can use this server immediately with no installation:

### 1. Install uv (if needed)
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 2. Add MCP Configuration

Add to `mcp.json` (VSCode) or `claude_desktop_config.json` (Claude Desktop):

```json
{
  "mcpServers": {
    "daily-utils": {
      "command": "uvx",
      "args": ["mcp-utility-kit"],
      "type": "stdio"
    }
  }
}
```

### 3. Reload MCP Client

That's it! No cloning, no manual installation needed.

**Package Link**: https://pypi.org/project/mcp-utility-kit/
**Repository**: https://github.com/thananauto/mcp-utility-kit

## Project Structure

```
mcp-utility-kit/
├── mcp_utility_kit/
│   ├── __init__.py       # Package initialization
│   ├── server.py         # MCP server implementation with tools
│   └── __main__.py       # Entry point
├── pyproject.toml        # Project configuration and dependencies
├── uv.lock              # Dependency lock file
└── README.md            # This file
```

## Development

### Built With

- **[FastMCP](https://github.com/jlowin/fastmcp)** - Framework for building MCP servers
- **[httpx](https://www.python-httpx.org/)** - Async HTTP client for API requests
- **[uv](https://docs.astral.sh/uv/)** - Fast Python package manager

### Adding New Tools

To add a new tool to the server:

1. Open [mcp_utility_kit/server.py](mcp_utility_kit/server.py)
2. Add a new function decorated with `@mcp.tool()`:

```python
@mcp.tool()
async def your_new_tool(param: str) -> str:
    """Tool description for LLM context.

    Args:
        param: Parameter description

    Returns:
        What the tool returns
    """
    # Your implementation here
    return "result"
```

3. Test locally with MCP Inspector
4. Rebuild and republish if deploying to PyPI

## Troubleshooting

### Server Won't Start

1. **Check uv is installed**:
   ```bash
   uv --version
   ```
   If not installed: `curl -LsSf https://astral.sh/uv/install.sh | sh`

2. **Test the server directly**:
   ```bash
   uvx mcp-utility-kit
   ```

3. **Check MCP configuration**: Ensure `mcp.json` has the correct format (see Installation section)

4. **View logs**: In VS Code, open Output panel (View → Output) and select "MCP" from dropdown

### Tools Not Appearing

- **Reload MCP client**: In VS Code, press `Cmd+Shift+P` → "Developer: Reload Window"
- **Check server status**: Look for "daily-utils" in the MCP Output logs
- **Verify configuration**: Double-check the JSON syntax in your `mcp.json`

### Package Version Issues

To force update to the latest version:
```bash
uvx --refresh mcp-utility-kit
```

### API Errors

- **Check internet connection**: All three APIs require internet access
- **Rate limits**: Free tier APIs may have rate limits
- **Regional restrictions**: Verify APIs are accessible from your location

### Getting Help

- **Check logs**: VS Code Output panel → MCP section shows detailed error messages
- **GitHub Issues**: https://github.com/thananauto/mcp-utility-kit/issues
- **MCP Documentation**: https://modelcontextprotocol.io/

## License

MIT License - see LICENSE file for details

## Contributing

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

## Support

For issues and questions:
- Open an issue in the repository
- Check existing issues for solutions
- Review the [MCP documentation](https://modelcontextprotocol.io/)