How do I use random-number-server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@random-number-server generate a random number using weather data from New York" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

random-number-server

codecov Python 3.13+ License

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" ] } } }