# Rust Plugins Quick Start Guide
Get started with Rust-accelerated plugins for MCP Gateway in under 5 minutes.
## Prerequisites
- Python 3.11+
- Rust 1.70+ (optional for building from source)
- Virtual environment activated
## Quick Install (Pre-built Wheels)
The fastest way to get started is using pre-built wheels (when available):
```bash
# Install MCP Gateway with Rust plugins
pip install mcpgateway[rust]
```
## Build from Source
If pre-built wheels aren't available for your platform, or you want to customize the build:
### 1. Install Rust Toolchain
```bash
# Install rustup (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Verify installation
rustc --version
cargo --version
```
### 2. Install Build Tools
```bash
# Install maturin (PyO3 build tool)
pip install maturin
# Optional: Install development tools
pip install cargo-watch cargo-tarpaulin
```
### 3. Build Rust Plugins
```bash
# Navigate to rust plugins directory
cd plugins_rust
# Development build (fast compilation, slower runtime)
make dev
# OR Production build (optimized for performance)
make build
# Verify installation
python -c "from plugins_rust import PIIDetectorRust; print('ā Rust plugins installed')"
```
**Build Times:**
- Development build: ~3-5 seconds
- Release build: ~7-10 seconds
## Starting the Gateway with Rust Plugins
### Method 1: Auto-Detection (Recommended)
The gateway automatically detects and uses Rust plugins when available:
```bash
# Activate virtual environment
source ~/.venv/mcpgateway/bin/activate # or your venv path
# Start development server
make dev
# OR start production server
make serve
```
The PII Filter plugin will automatically use the Rust implementation if installed.
### Method 2: Explicit Configuration
Force Rust plugin usage via environment variables:
```bash
# Enable plugins
export PLUGINS_ENABLED=true
export PLUGIN_CONFIG_FILE=plugins/config.yaml
# Start gateway
python -m mcpgateway.main
```
### Method 3: Direct Run
```bash
# From project root
cd /home/cmihai/github/mcp-context-forge
# Activate environment
source ~/.venv/mcpgateway/bin/activate
# Run with auto-reload (development)
uvicorn mcpgateway.main:app --reload --host 0.0.0.0 --port 8000
# OR run production server
gunicorn mcpgateway.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:4444
```
## Verify Rust Plugin is Active
### Check via Python
```python
from plugins.pii_filter.pii_filter import PIIFilterPlugin
from plugins.framework import PluginConfig
config = PluginConfig(name='pii_filter', kind='pii_filter', config={})
plugin = PIIFilterPlugin(config)
print(f"Implementation: {plugin.implementation}")
# Expected output: "Implementation: rust"
```
### Check via API
```bash
# Start the gateway
make dev
# In another terminal, make a request
curl -X POST http://localhost:8000/tools/invoke \
-H "Content-Type: application/json" \
-d '{
"tool_name": "detect_pii",
"arguments": {"text": "My SSN is 123-45-6789"}
}'
```
Check the server logs for:
```
INFO - Using Rust-accelerated PII filter (35x faster)
```
## Performance Verification
Run benchmarks to verify Rust acceleration:
```bash
# From plugins_rust directory
python benchmarks/compare_pii_filter.py
# OR with custom sizes
python benchmarks/compare_pii_filter.py --sizes 100 500 1000
# Save results to file
python benchmarks/compare_pii_filter.py --output benchmarks/results/latest.json
```
Expected output:
```
Average Speedup: 35.9x
š EXCELLENT: >10x speedup - Highly recommended
```
## Common Issues & Solutions
### Issue: "Rust implementation not available"
**Solution 1 - Install from source:**
```bash
cd plugins_rust
make dev
```
**Solution 2 - Check installation:**
```bash
python -c "from plugins_rust import PIIDetectorRust; print('OK')"
```
**Solution 3 - Rebuild:**
```bash
cd plugins_rust
make clean
make build
```
### Issue: Build fails with "maturin not found"
**Solution:**
```bash
pip install maturin
```
### Issue: Build fails with "cargo not found"
**Solution:**
```bash
# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```
### Issue: Gateway doesn't use Rust plugins
**Check 1 - Verify installation:**
```bash
python -c "import plugins_rust; print(plugins_rust.__file__)"
```
**Check 2 - Check logs:**
```bash
# Look for this line in gateway logs:
# "Using Rust-accelerated PII filter"
```
**Check 3 - Force Rust usage:**
```python
from plugins.pii_filter.pii_filter_rust import RustPIIDetector, RUST_AVAILABLE
print(f"Rust available: {RUST_AVAILABLE}")
```
### Issue: Import errors after building
**Solution - Add to Python path:**
```bash
export PYTHONPATH=/home/cmihai/github/mcp-context-forge:$PYTHONPATH
```
Or in Python:
```python
import sys
sys.path.insert(0, '/home/cmihai/github/mcp-context-forge')
```
## Development Workflow
### 1. Make Changes to Rust Code
```bash
cd plugins_rust
# Edit files in src/pii_filter/*.rs
```
### 2. Rebuild
```bash
# Fast rebuild with development mode
make dev
# OR full release build
make build
```
### 3. Test Changes
```bash
# Run Rust unit tests
make test
# Run Python integration tests
make test-python
# Run all tests
make test-all
```
### 4. Restart Gateway
```bash
# If using auto-reload (development)
# Changes are picked up automatically after rebuild
# If not using auto-reload
# Restart the gateway process
```
## Production Deployment
### 1. Build Optimized Release
```bash
cd plugins_rust
make build
```
### 2. Run Tests
```bash
make test-all
make verify
```
### 3. Deploy
```bash
# Copy wheel to production server
scp target/wheels/*.whl production-server:/tmp/
# On production server
pip install /tmp/mcpgateway_rust-*.whl
# Start gateway
gunicorn mcpgateway.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:4444
```
## Configuration
### Environment Variables
```bash
# Enable plugins
export PLUGINS_ENABLED=true
# Plugin configuration file
export PLUGIN_CONFIG_FILE=plugins/config.yaml
# Log level
export LOG_LEVEL=INFO
```
### Plugin Configuration (plugins/config.yaml)
```yaml
plugins:
- name: pii_filter
enabled: true
module: plugins.pii_filter.pii_filter
class: PIIFilterPlugin
priority: 100
config:
mask_strategy: partial
detect_ssn: true
detect_credit_card: true
detect_email: true
detect_phone: true
detect_ip: true
```
## Next Steps
1. **Read Full Documentation**: `docs/docs/using/plugins/rust-plugins.md`
2. **Run Benchmarks**: `python benchmarks/compare_pii_filter.py`
3. **Review Test Results**: `plugins_rust/BUILD_AND_TEST_RESULTS.md`
4. **Explore Examples**: Check `tests/unit/mcpgateway/plugins/test_pii_filter_rust.py`
5. **Join Development**: See `plugins_rust/README.md` for contribution guidelines
## Performance Summary
With Rust plugins enabled, you get:
- **7-18x faster** for typical PII detection
- **27-77x faster** for large datasets (100-1000 instances)
- **100x faster** for clean text (no PII)
- **35.9x average speedup** across all workloads
## Support
- **Issues**: https://github.com/anthropics/mcp-context-forge/issues
- **Documentation**: `docs/docs/using/plugins/rust-plugins.md`
- **Build Results**: `plugins_rust/BUILD_AND_TEST_RESULTS.md`
- **Makefile Help**: `cd plugins_rust && make help`
---
**Quick Command Reference:**
```bash
# Install
pip install mcpgateway[rust]
# Build from source
cd plugins_rust && make build
# Start gateway
make dev
# Run benchmarks
python benchmarks/compare_pii_filter.py
# Run tests
cd plugins_rust && make test-all
# Get help
cd plugins_rust && make help
```
