chuk-mcp-math-server 0.2.0

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

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

# Install dependencies
uv sync
# or
pip install -e .

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):

{
  "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

# Install development dependencies
uv sync --group dev

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

# Run tests with coverage
make test-cov

# Run type checking
make typecheck

# Format code
make format

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

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()

📊 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