BC Calculator MCP Server

# BC Calculator MCP Server - Python Implementation A Model Context Protocol (MCP) server that provides numerical computation capabilities by integrating with the Unix `bc` (Basic Calculator) command-line tool. This is the **Python implementation** using asyncio and the Python MCP SDK. > **Note**: This project includes both [TypeScript](README.md) and Python implementations for educational comparison. See [COMPARISON_GUIDE.md](COMPARISON_GUIDE.md) for details. ## Features - ✨ **Arbitrary Precision Arithmetic**: Support for calculations with configurable decimal precision (0-100 digits) - 🧮 **Advanced Math Functions**: Access to bc's math library including sqrt, sin, cos, arctan, natural log, exponential - 🔄 **Concurrent Processing**: Asyncio-based process pool for handling multiple calculations simultaneously - 🛡️ **Security First**: Input validation and sanitization to prevent command injection - ⚡ **Performance Optimized**: Process pooling with asyncio.Semaphore for fast response times - 🎯 **MCP Compliant**: Full MCP protocol implementation with tool discovery and JSON-RPC communication ## Installation ### Prerequisites - **Python** 3.10 or higher - **bc** calculator (standard on most Unix systems) - **pip** or **pip3** package manager Verify requirements: ```bash python3 --version # Should be 3.10+ which bc bc --version ``` If bc is not installed: ```bash # Ubuntu/Debian sudo apt-get install bc # macOS brew install bc # Fedora/RHEL sudo dnf install bc ``` ### Setup 1. **Navigate to the project directory**: ```bash cd /home/travis/.local/share/Roo-Code/MCP/bc-calculator ``` 2. **Create a virtual environment** (recommended): ```bash python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 3. **Install the package**: Option A - Development install (recommended for testing): ```bash pip install -e . ``` Option B - Install from requirements: ```bash pip install -r requirements.txt ``` 4. **Verify installation**: ```bash python3 -m bc_calculator_mcp --help 2>&1 | head -5 ``` 5. **Configure MCP settings**: Add to `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`: ```json { "mcpServers": { "bc-calculator-py": { "command": "python3", "args": ["-m", "bc_calculator_mcp"], "cwd": "/home/travis/.local/share/Roo-Code/MCP/bc-calculator/src/python" } } } ``` Or if using virtual environment: ```json { "mcpServers": { "bc-calculator-py": { "command": "/home/travis/.local/share/Roo-Code/MCP/bc-calculator/venv/bin/python", "args": ["-m", "bc_calculator_mcp"] } } } ``` ## Usage ### Available Tools #### 1. `calculate` Evaluate basic mathematical expressions with configurable precision. **Parameters**: - `expression` (string, required): Mathematical expression to evaluate - `precision` (number, optional): Decimal places for the result (default: 20, range: 0-100) **Examples**: ```python # Via MCP client { "name": "calculate", "arguments": { "expression": "2 + 2" } } # → {"result": "4", "expression": "2 + 2", "precision": 20} # Division with precision { "name": "calculate", "arguments": { "expression": "355/113", "precision": 15 } } # → {"result": "3.141592920353982", "expression": "355/113", "precision": 15} # Powers and roots { "name": "calculate", "arguments": { "expression": "sqrt(2)", "precision": 10 } } # → {"result": "1.4142135623", "expression": "sqrt(2)", "precision": 10} ``` #### 2. `calculate_advanced` Execute advanced BC scripts with variables, functions, and control flow. **Parameters**: - `script` (string, required): Multi-line BC script - `precision` (number, optional): Decimal places for results (default: 20) **Examples**: ```python # Variables { "name": "calculate_advanced", "arguments": { "script": "a = 5\nb = 10\na * b + sqrt(a)", "precision": 5 } } # Computing pi { "name": "calculate_advanced", "arguments": { "script": "scale=15\npi = 4*a(1)\npi" } } # → {"result": "3.141592653589793", ...} # Fibonacci sequence { "name": "calculate_advanced", "arguments": { "script": "a = 0\nb = 1\nfor (i = 0; i < 10; i++) {\n c = a + b\n a = b\n b = c\n}\nb" } } ``` #### 3. `set_precision` Set the default precision for subsequent calculations. **Parameters**: - `precision` (number, required): Number of decimal places (0-100) **Example**: ```python { "name": "set_precision", "arguments": { "precision": 50 } } # All subsequent calculations will use 50 decimal places ``` ### Mathematical Functions (with -l flag) When using the math library, these functions are available: | Function | Description | Example | |----------|-------------|---------| | `sqrt(x)` | Square root | `sqrt(2)` → 1.41421... | | `s(x)` | Sine (radians) | `s(3.14159/2)` → 1.0 | | `c(x)` | Cosine (radians) | `c(0)` → 1.0 | | `a(x)` | Arctangent (radians) | `a(1)` → 0.78539... | | `l(x)` | Natural logarithm | `l(2.71828)` → 1.0 | | `e(x)` | Exponential (e^x) | `e(1)` → 2.71828... | ### Direct Python Usage You can also use the Python implementation directly: ```python import asyncio from bc_calculator_mcp.bc_process_pool import BCProcessPool from bc_calculator_mcp.types import ProcessPoolConfig from bc_calculator_mcp.input_validator import InputValidator async def main(): # Initialize pool pool = BCProcessPool(ProcessPoolConfig( pool_size=3, default_precision=20, default_timeout=30000 )) await pool.initialize() # Validate and calculate validation = InputValidator.validate("355/113") if validation.valid: process = await pool.acquire_process() await process.set_precision(15) result = await process.evaluate(validation.sanitized) pool.release_process(process) print(f"Result: {result}") await pool.shutdown() asyncio.run(main()) ``` ## Architecture ### Python-Specific Design The Python implementation uses async/await patterns with asyncio for concurrent operations: ``` ┌─────────────────────────────────────┐ │ BC Calculator MCP Server (Python) │ ├─────────────────────────────────────┤ │ MCP Server (__main__.py) │ │ • Decorator-based tool registration │ │ • Async handlers │ ├─────────────────────────────────────┤ │ Input Validator (input_validator.py)│ │ • Regex validation │ │ • Security checks │ ├─────────────────────────────────────┤ │ BC Process Pool (bc_process_pool.py)│ │ • asyncio.Semaphore (concurrency) │ │ • asyncio.Queue (available pool) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Process │ │ Process │ │ Process │ │ │ │ (async) │ │ (async) │ │ (async) │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────┘ ``` ### Key Components 1. **Type Definitions** (`types.py`) - Uses `@dataclass` for structured data - `BCErrorCode` enum for error classification - Type hints throughout 2. **BC Process** (`bc_process.py`) - Wraps `asyncio.create_subprocess_exec` - `asyncio.Lock` for thread-safe operations - `asyncio.wait_for` for timeout handling 3. **Process Pool** (`bc_process_pool.py`) - `asyncio.Semaphore` for concurrency control - `asyncio.Queue` for available processes - Automatic process recovery 4. **MCP Server** (`__main__.py`) - Decorator-based tool registration - Async tool handlers - Signal handling for graceful shutdown See [ARCHITECTURE_PYTHON.md](ARCHITECTURE_PYTHON.md) for detailed design decisions. ## Development ### Project Structure ``` bc-calculator/ ├── pyproject.toml # Python project configuration ├── requirements.txt # Dependencies ├── README_PYTHON.md # This file ├── src/python/ # Python source │ └── bc_calculator_mcp/ │ ├── __init__.py │ ├── __main__.py # MCP server entry point │ ├── types.py # Type definitions │ ├── bc_process.py # BC process wrapper │ ├── bc_process_pool.py # Process pool manager │ └── input_validator.py # Security validation └── tests/ # Test suite (optional) ``` ### Running the Server ```bash # Activate virtual environment source venv/bin/activate # Run directly python3 -m bc_calculator_mcp # Or if installed as script bc-calculator-py ``` ### Testing ```bash # Run tests with pytest pytest # Run with coverage pytest --cov=bc_calculator_mcp --cov-report=html # Type checking with mypy mypy src/python/bc_calculator_mcp # Linting with ruff ruff check src/python/bc_calculator_mcp ``` ### Manual Testing ```bash # Test calculation via stdin (simulating MCP protocol) echo '{"expression": "2+2"}' | python3 -m bc_calculator_mcp ``` ## Configuration ### Default Settings - **Process Pool Size**: 3 concurrent BC processes - **Default Precision**: 20 decimal places - **Calculation Timeout**: 30 seconds (30,000 ms) - **Max Expression Length**: 10,000 characters ### Environment Variables None required - bc is a standard system utility. ### Custom Configuration Edit `src/python/bc_calculator_mcp/__main__.py` to adjust: ```python pool = BCProcessPool( ProcessPoolConfig( pool_size=5, # Increase for more concurrency default_precision=20, default_timeout=60000 # 60 second timeout ) ) ``` ## Troubleshooting ### BC Not Found **Error**: `BC calculator not found` **Solution**: Install bc calculator ```bash sudo apt-get install bc # Ubuntu/Debian brew install bc # macOS ``` ### Python Version Error **Error**: `Python 3.10+ required` **Solution**: Upgrade Python or use pyenv ```bash # Check version python3 --version # Install Python 3.10+ via pyenv pyenv install 3.10.0 pyenv local 3.10.0 ``` ### Module Import Errors **Error**: `No module named 'bc_calculator_mcp'` **Solution**: Install in development mode ```bash pip install -e . ``` ### MCP Server Not Responding **Issue**: Server starts but doesn't respond **Solutions**: 1. Check that bc is installed: `which bc` 2. Verify Python version: `python3 --version` 3. Check stderr output for initialization errors 4. Ensure MCP settings path is correct ### Permission Issues **Error**: `Permission denied` **Solution**: Fix script permissions ```bash chmod +x src/python/bc_calculator_mcp/__main__.py ``` ## Performance ### Benchmarks - **Simple arithmetic**: <10ms - **Division with precision**: <20ms - **Math functions**: <50ms - **Complex scripts**: <200ms - **Pool initialization**: ~300ms - **Concurrent requests**: 3 parallel calculations ### Optimization Tips 1. **Reuse the pool**: Process pool automatically optimizes this 2. **Batch operations**: Use `calculate_advanced` for multiple related calculations 3. **Adjust precision**: Lower precision = faster calculations 4. **Increase pool**: For heavy concurrent use, increase `pool_size` ## Comparison with TypeScript | Aspect | Python | TypeScript | |--------|--------|------------| | Async Model | asyncio | Promises | | Type System | Type hints + dataclasses | Interfaces | | Process Management | asyncio.subprocess | child_process | | Concurrency | Semaphore + Queue | Array + state | | SDK Style | Decorators | Functional | | Performance | ~same | ~same | See [COMPARISON_GUIDE.md](COMPARISON_GUIDE.md) for detailed comparison. ## Contributing 1. Follow PEP 8 style guidelines 2. Add type hints to all functions 3. Write tests for new features 4. Update documentation 5. Run linters before committing: ```bash ruff check src/python/bc_calculator_mcp mypy src/python/bc_calculator_mcp ``` ## License MIT License - See [LICENSE](LICENSE) file for details ## Acknowledgments - Built on the [Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk) - Uses the standard [GNU bc](https://www.gnu.org/software/bc/) calculator - Python implementation inspired by TypeScript version for educational purposes ## Support For issues, questions, or feature requests: 1. Check the [Troubleshooting](#troubleshooting) section 2. Review [IMPLEMENTATION_GUIDE_PYTHON.md](IMPLEMENTATION_GUIDE_PYTHON.md) 3. Examine [ARCHITECTURE_PYTHON.md](ARCHITECTURE_PYTHON.MD) ## Version History ### 1.0.0 (Initial Dual-Language Release) - Python implementation matching TypeScript functionality - Asyncio-based process pool - Pythonic design patterns - Full MCP protocol compliance - Comprehensive documentation