# MCP Utility Kit

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

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
- 📦 Installable via PyPI or local development

## Installation

### Prerequisites

- Python 3.13 or higher
- [uv](https://docs.astral.sh/uv/) package manager (recommended)

### Option 1: Install from PyPI (After Publishing)

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

Or use directly with `uvx` (no installation needed):

```bash
uvx mcp-utility-kit
```

### Option 2: Local Development Setup

1. Clone the repository:
```bash
git clone <repository-url>
cd mcp-utility-kit
```

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

## MCP Client Configuration

### For Local Development

Add to your MCP configuration 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": "uv",
      "args": [
        "run",
        "--directory",
        "/full/path/to/mcp-utility-kit",
        "python",
        "-m",
        "mcp_utility_kit"
      ],
      "type": "stdio"
    }
  }
}
```

**Note**: Replace `/full/path/to/mcp-utility-kit` with the actual path where you cloned this repository.

### After Publishing to PyPI

Once published, your team can use the simpler configuration:

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

### Reload Your MCP Client

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

## Usage

### Running Locally in Terminal

```bash
# From the project directory
cd /path/to/mcp-utility-kit

# Run with uv
uv run python -m mcp_utility_kit

# Or directly with Python
python -m mcp_utility_kit
```

### Testing with MCP Inspector

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

```bash
npx @modelcontextprotocol/inspector uv run --directory /path/to/mcp-utility-kit python -m mcp_utility_kit
```

This opens a browser interface where you can test all the 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

## Publishing to PyPI

To publish this package to PyPI for easy team distribution:

### 1. Prepare for Publishing

Update the package information in [pyproject.toml](pyproject.toml):
- Update `authors` with your information
- Update `project.urls` with your repository URLs
- Increment the `version` number for updates

### 2. Build the Package

```bash
uv build
```

This creates distribution files in the `dist/` directory.

### 3. Publish to PyPI

Install publishing tools:
```bash
pip install twine
```

Upload to PyPI (requires PyPI account and credentials):
```bash
twine upload dist/*
```

Or upload to Test PyPI first:
```bash
twine upload --repository testpypi dist/*
```

### 4. Verify Installation

After publishing, test the installation:
```bash
pip install mcp-utility-kit

# Or use directly
uvx mcp-utility-kit
```

## Sharing with Team Members

### Option 1: Via PyPI (Recommended)

Once published to PyPI, team members can use it immediately:

1. **No clone needed** - `uvx` will automatically download and run it
2. **Simple configuration** - Add to `mcp.json`:
```json
{
  "mcpServers": {
    "daily-utils": {
      "command": "uvx",
      "args": ["mcp-utility-kit"],
      "type": "stdio"
    }
  }
}
```
3. **Reload MCP client** - Done!

### Option 2: Via Git Repository

For development or before PyPI publishing:

1. **Share the repository**:
   - Push to GitHub, GitLab, or your internal Git server
   - Share the repository URL

2. **Team members install**:
```bash
git clone <repository-url>
cd mcp-utility-kit
uv sync
```

3. **Configure MCP client** with local path (see configuration section above)

4. **Reload MCP client**

## 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

- Verify Python 3.13+ is installed: `python --version`
- Check configuration path in `mcp.json` is correct
- Ensure `uv` is installed: `uv --version`
- Try running directly: `uv run python -m mcp_utility_kit`

### Tools Not Appearing

- Reload your MCP client
- Check server logs in VS Code Output panel (MCP section)
- Verify the server started successfully

### API Errors

- Check your internet connection
- Verify the APIs are accessible (no regional restrictions)
- Check API response in terminal by running server directly

## 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/)
