random-number-mcp AGENTS.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Install dependencies
uv sync --dev

# Run tests
uv run pytest

# Run a single test
uv run pytest tests/test_tools.py::test_function_name

# Lint and format
uv run ruff check --fix
uv run ruff format

# Type checking
uv run mypy src/

# Run server locally
uv run random-number-mcp

# Build package
uv build

# Inspect/test with MCP Inspector
npx @modelcontextprotocol/inspector uv run random-number-mcp

Architecture

The package is a FastMCP server with a three-layer structure:

• server.py — FastMCP app instance and @app.tool() decorated endpoints. Handles MCP protocol concerns (e.g., JSON string weights parsing). Entry point is main().
• tools.py — Pure Python business logic, calls random and secrets stdlib modules. No FastMCP dependency; testable in isolation.
• utils.py — Shared validation helpers used by tools.py.

Tools fall into two categories: standard pseudorandom (random module) and cryptographically secure (secrets module).

Release Process

The Release Checklist in README.md is canonical — follow it, don't work from memory. Notes for agents:

• The version lives in four fields across three files: pyproject.toml, src/random_number_mcp/__init__.py, and server.json (which carries it both at the top level and under packages[0]). Miss one and the release ships inconsistent metadata.
• CHANGELOG.md is updated as part of the same commit as the version bump.
• Release from main, with the branch merged and pushed first. Fetch before assuming local main is current — work is sometimes merged upstream via PR, so a local-only merge can leave you diverged.

Cutting the release

Always ask the maintainer for explicit confirmation before this step. Creating the release publishes to PyPI automatically via the release: published trigger in .github/workflows/publish.yml, and that is irreversible — a version can never be overwritten or reused on PyPI.