chuk-mcp-math-server 0.2.1

Configurable mathematical computation server for MCP protocol

🧮 Chuk MCP Math Server

A highly configurable Mathematical Computation Protocol (MCP) server that provides comprehensive mathematical functions with flexible transport options. Built on the high-performance chuk-mcp-server framework.

⚡ Performance

• 36,000+ RPS peak throughput (inherited from chuk-mcp-server)
• Sub-3ms latency per tool call
• 393 Mathematical Functions available
• Zero-config startup - works out of the box

✨ Features

🔢 Mathematical Capabilities

• 393 Mathematical Functions across multiple domains
• Number Theory: Prime testing, factorization, GCD, LCM, sequences (71 functions)
• Arithmetic: Basic operations, advanced calculations, statistics (322 functions)
• Trigonometry: Comprehensive trigonometric operations (71 functions)
• Real-time Computation: Async processing with proper error handling
• Function Filtering: Configurable allowlists and denylists by domain, category, or function

🚀 Transport & Architecture

• Dual Transport: STDIO (Claude Desktop) and HTTP support
• High Performance: Built on chuk-mcp-server framework
• Auto-detection: Automatically selects optimal transport mode
• Production Ready: 36,000+ RPS, <3ms latency
• Type Safe: Automatic schema generation from Python type hints

⚙️ Configuration

• CLI Configuration: Comprehensive command-line options
• File Configuration: YAML and JSON config file support
• Environment Variables: Container-friendly configuration
• Dynamic Filtering: Runtime function filtering with allowlists and denylists
• Granular Control: Filter by function, domain, or category

🛡️ Production Features

• Zero Configuration: Works out of the box with sensible defaults
• High Test Coverage: 97% code coverage with 114 comprehensive tests
• Type Safe: 100% type-checked with mypy, fully Pydantic-native
• Error Handling: Graceful failure management
• Logging: Configurable log levels and output
• MCP Resources: Built-in resources for function discovery and stats
• Timeout Management: Configurable computation timeouts

🚀 Quick Start

Installation

Using uvx (Recommended - No Installation Required!)

The easiest way to use the server is with uvx, which runs it without installing:

uvx chuk-mcp-math-server

This automatically downloads and runs the latest version. Perfect for Claude Desktop!

Using uv (Recommended for Development)

# Install from PyPI
uv pip install chuk-mcp-math-server

# Or clone and install from source
git clone https://github.com/chuk-mcp/chuk-mcp-math-server.git
cd chuk-mcp-math-server
uv sync

Using pip (Traditional)

pip install chuk-mcp-math-server

Basic Usage

STDIO Transport (Claude Desktop)

# Start server with STDIO transport (default)
uv run chuk-mcp-math-server

# Starts immediately with all 393 functions available

HTTP Transport (Web APIs)

# Start HTTP server
uv run chuk-mcp-math-server --transport http --port 8000

# Server will be available at http://localhost:8000

Claude Desktop Integration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Option 1: Using uvx (Easiest)

{
  "mcpServers": {
    "math": {
      "command": "uvx",
      "args": ["chuk-mcp-math-server"]
    }
  }
}

Option 2: Using Local Installation

{
  "mcpServers": {
    "math": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/chuk-mcp-math-server",
        "run",
        "chuk-mcp-math-server"
      ]
    }
  }
}

Important: Use absolute paths, not relative or ~ paths.

Restart Claude Desktop and ask: "Can you check if 97 is prime?" - Claude will use the math server!

Example HTTP API Usage

# Test the server
curl http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Call a mathematical function
curl http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "is_prime",
      "arguments": {"n": 97}
    }
  }'

📖 Documentation

Available Functions

The server provides 393 mathematical functions across these domains:

Domain	Functions	Examples
Arithmetic (322)	Basic operations, comparisons, rounding, modular arithmetic	add, multiply, modulo, gcd, lcm
Trigonometry (71)	Trig functions, conversions, identities	sin, cos, tan, radians, degrees
Number Theory	Primes, sequences, special numbers	is_prime, fibonacci, factorial, divisors

Function Filtering

Control which functions are exposed:

# Only expose specific functions
chuk-mcp-math-server --functions add subtract multiply divide

# Expose only arithmetic domain
chuk-mcp-math-server --domains arithmetic

# Exclude specific functions
chuk-mcp-math-server --exclude-functions slow_function

# Combine filters
chuk-mcp-math-server --domains arithmetic number_theory --categories core primes

Configuration Options

Command Line

# Basic configuration
chuk-mcp-math-server --transport http --port 8080 --host 0.0.0.0

# Function filtering
chuk-mcp-math-server --domains arithmetic --functions is_prime add

# Performance tuning
chuk-mcp-math-server --cache-strategy smart --timeout 60

# Logging
chuk-mcp-math-server --verbose  # Debug logging
chuk-mcp-math-server --quiet    # Minimal logging

Configuration File

# config.yaml
transport: "http"
port: 8000
host: "0.0.0.0"
log_level: "INFO"

# Function filtering (allowlist: only these are enabled, denylist: these are excluded)
domain_allowlist: ["arithmetic", "number_theory"]
function_allowlist: ["is_prime", "fibonacci", "add", "multiply"]
function_denylist: ["deprecated_function"]  # Exclude specific functions

# Performance
cache_strategy: "smart"
cache_size: 1000
computation_timeout: 30.0
max_concurrent_calls: 10

# Use configuration file
chuk-mcp-math-server --config config.yaml

# Save current config
chuk-mcp-math-server --domains arithmetic --save-config my-config.yaml

# Show current config
chuk-mcp-math-server --show-config

MCP Resources

The server provides built-in resources for introspection:

# List available functions (via MCP resource)
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/read",
  "params": {
    "uri": "math://available-functions"
  }
}

# Get function statistics
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "math://function-stats"
  }
}

# Get server configuration
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/read",
  "params": {
    "uri": "math://server-config"
  }
}

🛠️ Development

Project Structure

chuk-mcp-math-server/
├── src/chuk_mcp_math_server/
│   ├── __init__.py              # Package initialization
│   ├── cli.py                   # CLI implementation
│   ├── config.py                # Base configuration (Pydantic)
│   ├── math_config.py           # Math-specific configuration
│   ├── function_filter.py       # Function filtering logic
│   └── math_server.py           # Main server (uses chuk-mcp-server)
├── tests/                       # Test suite (97% coverage, 114 tests)
├── pyproject.toml              # Project configuration
└── README.md                   # This file

Development Setup

# Clone the repository
git clone https://github.com/chuk-mcp/chuk-mcp-math-server.git
cd chuk-mcp-math-server

# Install development dependencies
uv sync

# Install in editable mode
uv pip install -e ".[dev]"

Running Tests

# Run tests
make test

# Run tests with coverage
make test-cov

# Run specific test file
uv run pytest tests/test_config.py -v

Code Quality

# Run all quality checks (lint, typecheck, security, tests)
make check

# Format code
make format

# Run linting
make lint

# Run type checking
make typecheck

# Run security checks
make security

Building

# Build distribution packages
make build

# This creates wheel and source distributions in dist/

Running Locally

# Run with verbose logging
uv run chuk-mcp-math-server --verbose

# Run HTTP server
make run-http

# Run STDIO server (default)
make run

Custom Server

from chuk_mcp_math_server import create_math_server

# Create server with custom configuration
server = create_math_server(
    transport="http",
    port=9000,
    domain_allowlist=["arithmetic"],  # Only arithmetic functions
    function_denylist=["deprecated_func"],  # Exclude specific functions
    log_level="DEBUG"
)

# Run the server
server.run()

🚀 Deployment

Docker

Build and run with Docker:

# Build the Docker image
make docker-build

# Run the container
make docker-run

# Or manually:
docker build -t chuk-mcp-math-server .
docker run -p 8000:8000 chuk-mcp-math-server

The server will be available at http://localhost:8000.

Fly.io

Deploy to Fly.io for a public server:

# Install flyctl if you haven't already
curl -L https://fly.io/install.sh | sh

# Login to Fly.io
flyctl auth login

# Deploy (first time)
flyctl launch

# Or deploy updates
flyctl deploy

# Check status
flyctl status

# View logs
flyctl logs

The fly.toml configuration is already set up for HTTP mode on port 8000. The server will auto-scale based on traffic (min 0, auto-start/stop).

Environment Variables

Configure via Fly.io secrets:

# Set environment variables
flyctl secrets set MCP_SERVER_LOG_LEVEL=INFO
flyctl secrets set MCP_MATH_CACHE_STRATEGY=smart

# View secrets
flyctl secrets list

GitHub Actions

The repository includes automated workflows:

• Test: Runs on all PRs and commits (Ubuntu, Windows, macOS)
• Release: Creates GitHub releases when tags are pushed
• Publish: Publishes to PyPI automatically on releases
• Fly Deploy: Auto-deploys to Fly.io on main branch pushes

To create a release:

# Bump version in pyproject.toml
make bump-patch  # or bump-minor, bump-major

# Commit the version change
git add pyproject.toml uv.lock
git commit -m "Bump version to 0.2.1"
git push

# Create and push a tag to trigger release
make publish

This will automatically:

1. Create a GitHub release with changelog
2. Run tests on all platforms
3. Build and publish to PyPI
4. Deploy to Fly.io (if configured)

📊 Performance

Benchmarks

• Peak Throughput: 36,000+ requests/second
• Average Latency: <3ms per tool call
• Startup Time: ~2 seconds (393 functions loaded)
• Memory Usage: ~50MB baseline
• Success Rate: 100% under load testing

Performance comes from:

• chuk-mcp-server framework: High-performance MCP implementation
• Async operations: Non-blocking I/O for all function calls
• Type safety: Automatic schema validation with zero overhead
• Optimized registry: Fast function lookup and execution

Optimization Tips

• Use function filtering to reduce memory footprint
• Enable caching for repeated calculations (--cache-strategy smart)
• Use HTTP transport for web APIs, STDIO for local/Claude Desktop
• Adjust --max-concurrent-calls for high-throughput scenarios

🔧 Troubleshooting

Common Issues

Server Won't Start

# Verify installation
python -c "import chuk_mcp_math_server; print(chuk_mcp_math_server.__version__)"

# Verify configuration
chuk-mcp-math-server --show-config

# Debug mode
chuk-mcp-math-server --verbose

Functions Not Loading

# Check if chuk-mcp-math is installed
python -c "import chuk_mcp_math; print(chuk_mcp_math.__version__)"

# Verify function count
chuk-mcp-math-server --show-config | grep total_filtered

Claude Desktop Not Showing Tools

1. Use absolute paths in claude_desktop_config.json (not ~ or relative)
2. Test manually: echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | uv run chuk-mcp-math-server
3. Restart Claude Desktop after config changes
4. Check Claude Desktop logs (Help → Show Logs)

HTTP Connection Issues

# Test server health
curl http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

🤝 Contributing

We welcome contributions! Here's how to help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Ensure tests pass (pytest)
6. Submit a pull request

Code Style

• Follow PEP 8 guidelines
• Maintain 100% type safety with mypy and Pydantic
• Add type hints where appropriate
• Update documentation for new features
• Keep the README up to date
• Aim for high test coverage (currently 97%)

📋 Requirements

Core Dependencies

• Python 3.11+
• chuk-mcp-server >= 0.6 (provides high-performance MCP framework)
• chuk-mcp-math >= 0.1.0 (provides mathematical functions)
• pyyaml >= 6.0.2 (for YAML configuration)

What's Included via chuk-mcp-server

• High-performance HTTP/STDIO transport
• Automatic type inference and validation
• Built-in logging and error handling
• Zero-config startup capability
• Production-grade performance (36K+ RPS)

Optional Dependencies

• Development tools: pytest, pytest-asyncio
• All optional: pip install -e .[dev]

🏗️ Architecture

Built on chuk-mcp-server framework:

• chuk-mcp-server: High-performance MCP server framework (36K+ RPS)
• chuk-mcp-math: Mathematical function library (393 functions)
• This server: Bridges the two with filtering and configuration

The refactored architecture is simpler and more performant:

• Removed custom base server implementation
• Uses chuk-mcp-server's decorator-based API
• Maintains all filtering and configuration features
• Gains automatic performance optimization

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built on chuk-mcp-server - High-performance MCP framework
• Mathematical functions from chuk-mcp-math
• Follows the Model Context Protocol specification

🔗 Links

• chuk-mcp-server: GitHub | Docs
• chuk-mcp-math: GitHub
• MCP Protocol: Official Specification
• Issues: GitHub Issues

---

Made with ❤️ by the Chuk MCP Team

High-performance mathematical computation for the Model Context Protocol ecosystem