Skip to main content
Glama
nobelk

random-number-server

by nobelk

random-number-server

CI 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

Related MCP server: Random-Generator

Quick Start

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

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    A
    maintenance
    Production-ready MCP server that provides LLMs with essential random generation abilities, including random integers, floats, choices, shuffling, and cryptographically secure tokens.
    7
    50
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    An encrypted and secure random number generation server that complies with the MCP protocol, suitable for AI applications, LLMS, and other systems that require high-quality random numbers.
    7
    2
    Apache 2.0
  • F
    license
    Not graded
    quality
    D
    maintenance
    A FastMCP-based server providing tools for weather queries, random number generation, and real-time stock market data retrieval. It enables AI models to interact with external data and perform specific tasks through the Model Context Protocol.
    -