mcp-utility-kit 0.1.0

MCP server providing daily joke, weather data, and age prediction tools

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 package manager (recommended)

Option 1: Install from PyPI (After Publishing)

pip install mcp-utility-kit

Or use directly with uvx (no installation needed):

uvx mcp-utility-kit

Option 2: Local Development Setup

1. Clone the repository:

git clone <repository-url>
cd mcp-utility-kit

2. Install dependencies:

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)

{
  "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:

{
  "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

# 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 provides a web UI for testing your MCP server:

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:

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:

predict_age_by_name(name="Michael")

APIs Used

This server integrates with the following free APIs:

• Official Joke API - Random jokes
• Open-Meteo Weather API - Weather data (no API key required)
• Agify Age Prediction API - 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:

• Update authors with your information
• Update project.urls with your repository URLs
• Increment the version number for updates

2. Build the Package

uv build

This creates distribution files in the dist/ directory.

3. Publish to PyPI

Install publishing tools:

pip install twine

Upload to PyPI (requires PyPI account and credentials):

twine upload dist/*

Or upload to Test PyPI first:

twine upload --repository testpypi dist/*

4. Verify Installation

After publishing, test the installation:

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:

{
  "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:

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 - Framework for building MCP servers
• httpx - Async HTTP client for API requests
• uv - Fast Python package manager

Adding New Tools

To add a new tool to the server:

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

@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