random-number-server

MCP server to generate random numbers using the national weather data as seeds.

Build Instructions

Local Development Build

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/nobelk/random-number-server.git
cd random-number-server

# Install dependencies and build the project
uv sync

# Install in editable mode for development
uv pip install -e .

Docker Build

# Build the Docker image
docker build -t random-number-server:latest .

# Or use Docker Compose to build
docker-compose build

Quick Start

Using Docker Compose (Recommended)

# Build and run the server
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

Using uv directly

# Install dependencies
uv sync

# Run the server
uv run src/random_server.py

Unit Tests

The project includes comprehensive unit tests for both core modules with 86% code coverage.

Running Tests

# Install dependencies
uv sync

# Run all tests
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Run tests with coverage report
uv run pytest --cov=src --cov-report=term-missing

# Run specific test files
uv run pytest tests/test_random_number_generator.py
uv run pytest tests/test_random_server.py

Test Coverage

• src/RandomNumberGenerator.py: 83% coverage (13 tests)
• src/random_server.py: 92% coverage (17 tests)
• Total: 86% coverage (30 tests)

Tests cover:

• Initialization and configuration
• Random number generation algorithms
• Weather API integration
• Error handling and edge cases
• FastMCP tool registration and execution
• Concurrent request handling

Docker Setup

The project includes Docker and Docker Compose configurations for easy deployment.

Docker Image

• Base: Python 3.13 Alpine (optimized for size)
• Size: ~110MB
• Security: Runs as non-root user
• Build: Multi-stage build for optimization

Docker Compose

# Production
docker-compose up -d

# Development (with live reload)
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

# Run tests in container
docker-compose run --rm --entrypoint /app/.venv/bin/python random-server -m pytest

See README_DOCKER.md for detailed Docker instructions.

MCP Configuration

Run the MCP server locally

uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/random-number-server run src/random_server.py

Configure Claude Desktop

Edit ~/Library/Application\ Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "weather": {
      "command": "/Users/Nobel.Khandaker/.pyenv/shims/uv",
      "args": [
        "--directory",
        "/Users/Nobel.Khandaker/sources/random-number-server",
        "run",
        "src/random_server.py"
      ]
    }
  }
}