Skip to content

Latest commit

 

History

History
389 lines (278 loc) · 7.5 KB

QUICKSTART.md

File metadata and controls

389 lines (278 loc) · 7.5 KB

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

# 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

# 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

# Install maturin (PyO3 build tool)
pip install maturin

# Optional: Install development tools
pip install cargo-watch cargo-tarpaulin

3. Build Rust Plugins

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

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

# Enable plugins
export PLUGINS_ENABLED=true
export PLUGIN_CONFIG_FILE=plugins/config.yaml

# Start gateway
python -m mcpgateway.main

Method 3: Direct Run

# 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

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

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

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

cd plugins_rust
make dev

Solution 2 - Check installation:

python -c "from plugins_rust import PIIDetectorRust; print('OK')"

Solution 3 - Rebuild:

cd plugins_rust
make clean
make build

Issue: Build fails with "maturin not found"

Solution:

pip install maturin

Issue: Build fails with "cargo not found"

Solution:

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

python -c "import plugins_rust; print(plugins_rust.__file__)"

Check 2 - Check logs:

# Look for this line in gateway logs:
# "Using Rust-accelerated PII filter"

Check 3 - Force Rust usage:

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:

export PYTHONPATH=/home/cmihai/github/mcp-context-forge:$PYTHONPATH

Or in Python:

import sys
sys.path.insert(0, '/home/cmihai/github/mcp-context-forge')

Development Workflow

1. Make Changes to Rust Code

cd plugins_rust
# Edit files in src/pii_filter/*.rs

2. Rebuild

# Fast rebuild with development mode
make dev

# OR full release build
make build

3. Test Changes

# Run Rust unit tests
make test

# Run Python integration tests
make test-python

# Run all tests
make test-all

4. Restart Gateway

# 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

cd plugins_rust
make build

2. Run Tests

make test-all
make verify

3. Deploy

# 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

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

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

Quick Command Reference:

# 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