Skip to Content
Nextra 2 Alpha
ArchitectureMCPRhema MCP Daemon Quick Reference

Rhema MCP Daemon Quick Reference

Quick Start Commands

Installation

# Build from source
 
 
cargo build --release
cargo install --path .
 
# Or download binary
 
 
curl -L https://github.com/fugue-ai/rhema/releases/latest/download/rhema-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv rhema /usr/local/bin/

Basic Usage

# Start daemon with defaults
 
 
rhema daemon start
 
# Start with custom config
 
 
rhema daemon start --config rhema-mcp.yaml
 
# Start with command line options
 
 
rhema daemon start --host 0.0.0.0 --port 8080 --auth --api-key "your-key"
 
# Stop daemon
 
 
rhema daemon stop
 
# Check status
 
 
rhema daemon status

Configuration Quick Reference

Minimal Configuration

host: "127.0.0.1"
port: 8080
auth:
  enabled: false
watcher:
  enabled: true
  watch_dirs: [".rhema"]
cache:
  memory_enabled: true
  ttl_seconds: 3600

Production Configuration

host: "0.0.0.0"
port: 8080
unix_socket: "/var/run/rhema-mcp.sock"
redis_url: "redis://redis:6379"
 
auth:
  enabled: true
  api_key: "${Rhema_API_KEY}"
  jwt_secret: "${Rhema_JWT_SECRET}"
  allowed_origins: ["https://your-app.example.com"]
 
watcher:
  enabled: true
  watch_dirs: [".rhema", "config"]
  file_patterns: ["*.yaml", "*.yml"]
  debounce_ms: 100
 
cache:
  memory_enabled: true
  redis_enabled: true
  ttl_seconds: 3600
  max_size: 10000
 
logging:
  level: "info"
  structured: true
  file: "/var/log/rhema-mcp.log"

API Quick Reference

Health Check

curl http://localhost:8080/health

List Scopes

curl http://localhost:8080/scopes

Execute Query

curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM scopes"}'

Get Resource

curl http://localhost:8080/resources/rhema%3A//scopes/test/scope.yaml

With Authentication

curl -H "Authorization: Bearer your-api-key" \
  http://localhost:8080/scopes

WebSocket Quick Reference

Connect

const ws = new WebSocket('ws://localhost:8081/ws');

Send Request

ws.send(JSON.stringify({
  jsonrpc: "2.0",
  id: 1,
  method: "system/health",
  params: {}
}));

Subscribe to Changes

ws.send(JSON.stringify({
  jsonrpc: "2.0",
  id: 2,
  method: "resources/subscribe",
  params: { uri: "rhema://scopes/test" }
}));

Unix Socket Quick Reference

Connect

nc -U /tmp/rhema-mcp.sock

Send Request

echo '{"jsonrpc": "2.0", "id": 1, "method": "system/health", "params": {}}' | nc -U /tmp/rhema-mcp.sock

Docker Quick Reference

Build Image

docker build -t rhema-mcp .

Run Container

docker run -d \
  --name rhema-mcp \
  -p 8080:8080 \
  -v $(pwd)/.rhema:/app/.rhema:ro \
  -e Rhema_API_KEY=your-key \
  rhema-mcp

Docker Compose

# Start
 
 
docker-compose up -d
 
# Stop
 
 
docker-compose down
 
# View logs
 
 
docker-compose logs -f rhema-mcp

Kubernetes Quick Reference

Deploy

kubectl apply -f k8s/

Check Status

kubectl get pods -n rhema
kubectl logs -f deployment/rhema-mcp -n rhema

Scale

kubectl scale deployment rhema-mcp --replicas=5 -n rhema

Port Forward

kubectl port-forward service/rhema-mcp-service 8080:80 -n rhema

Environment Variables

VariableDescriptionDefault
Rhema_API_KEYAPI key for authenticationNone
Rhema_JWT_SECRETJWT secret for token generationNone
Rhema_REDIS_URLRedis connection URLNone
Rhema_LOG_LEVELLog level (trace, debug, info, warn, error)info
Rhema_LOG_FILELog file pathNone
Rhema_HOSTHost to bind to127.0.0.1
Rhema_PORTPort to bind to8080

Common Queries

List All Scopes

SELECT * FROM scopes

Find Service Scopes

SELECT * FROM scopes WHERE type = 'service'

Search Knowledge

SELECT * FROM knowledge WHERE content LIKE '%architecture%'

Find High Priority Todos

SELECT * FROM todos WHERE priority = 'high' AND status != 'completed'

Recent Decisions

SELECT * FROM decisions WHERE created_at > '2024-01-01'

Troubleshooting Quick Reference

Daemon Won’t Start

# Check if port is in use
 
 
sudo lsof -i :8080
 
# Check permissions
 
 
ls -la /tmp/rhema-mcp.sock
 
# Check logs
 
 
tail -f /var/log/rhema-mcp.log

Authentication Issues

# Test API key
 
 
curl -H "Authorization: Bearer your-key" http://localhost:8080/health
 
# Check environment variable
 
 
echo $Rhema_API_KEY

Redis Connection Issues

# Test Redis
 
 
redis-cli ping
 
# Check Redis URL
 
 
echo $Rhema_REDIS_URL

File Watching Issues

# Check inotify limits
 
 
cat /proc/sys/fs/inotify/max_user_watches
 
# Increase limits
 
 
echo 524288 | sudo tee /proc/sys/fs/inotify/max_user_watches

Performance Issues

# Check memory usage
 
 
curl http://localhost:8080/health | jq '.memory_usage'
 
# Check cache hit rate
 
 
curl http://localhost:8080/health | jq '.cache_hit_rate'
 
# Monitor connections
 
 
watch -n 5 'curl -s http://localhost:8080/health | jq ".connections"'

Monitoring Commands

Health Check

# Basic health
 
 
curl -f http://localhost:8080/health || exit 1
 
# Detailed health
 
 
curl http://localhost:8080/health | jq '.'
 
# Specific metrics
 
 
curl http://localhost:8080/health | jq '.memory_usage'
curl http://localhost:8080/health | jq '.cache_hit_rate'

Statistics

# Get stats
 
 
curl http://localhost:8080/stats | jq '.'
 
# Cache stats
 
 
curl http://localhost:8080/stats | jq '.cache_stats'
 
# File stats
 
 
curl http://localhost:8080/stats | jq '.file_stats'

Log Monitoring

# Follow logs
 
 
tail -f /var/log/rhema-mcp.log
 
# Search for errors
 
 
grep ERROR /var/log/rhema-mcp.log
 
# Search for warnings
 
 
grep WARN /var/log/rhema-mcp.log
 
# Monitor real-time
 
 
tail -f /var/log/rhema-mcp.log | grep -E "(ERROR|WARN)"

Security Quick Reference

Generate API Key

# Generate random API key
 
 
openssl rand -hex 32
 
# Generate JWT secret
 
 
openssl rand -base64 64

Secure Configuration

# Production security settings
 
 
host: "127.0.0.1"  # Bind to localhost only
auth:
  enabled: true
  api_key: "${Rhema_API_KEY}"
  allowed_origins: ["https://your-app.example.com"]

Network Security

# Firewall rules (iptables)
 
 
sudo iptables -A INPUT -p tcp --dport 8080 -s 192.168.1.0/24 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 8080 -j DROP
 
# Firewall rules (ufw)
 
 
sudo ufw allow from 192.168.1.0/24 to any port 8080

Backup and Recovery

Backup Configuration

# Backup config
 
 
cp rhema-mcp.yaml rhema-mcp.yaml.backup
 
# Backup with timestamp
 
 
cp rhema-mcp.yaml rhema-mcp.yaml.$(date +%Y%m%d_%H%M%S)

Backup Data

# Backup Redis data
 
 
redis-cli BGSAVE
 
# Backup logs
 
 
cp /var/log/rhema-mcp.log /backup/rhema-mcp.log.$(date +%Y%m%d)

Restore

# Restore config
 
 
cp rhema-mcp.yaml.backup rhema-mcp.yaml
 
# Restart daemon
 
 
rhema daemon restart

Performance Tuning

Memory Optimization

# High memory configuration
 
 
cache:
  max_size: 50000
  ttl_seconds: 7200
 
logging:
  level: "warn"  # Less verbose

CPU Optimization

# High performance configuration
 
 
watcher:
  debounce_ms: 50  # Faster response
 
cache:
  memory_enabled: true
  redis_enabled: true

Network Optimization

# Network optimization
 
 
host: "0.0.0.0"
port: 8080
unix_socket: "/var/run/rhema-mcp.sock"  # For local access

Common Error Messages

ErrorCauseSolution
Port already in useAnother service using port 8080Change port or stop conflicting service
Permission deniedUnix socket permissionschmod 660 /tmp/rhema-mcp.sock
Redis connection failedRedis not running or wrong URLStart Redis or check URL
Authentication failedInvalid API keyCheck API key configuration
File not foundMissing .rhema directoryCreate .rhema directory and scope files
Memory limit exceededCache too largeReduce cache size or increase memory

Development Quick Reference

Debug Mode

# Start with debug logging
 
 
rhema daemon start --log-level debug
 
# Or modify config
 
 
sed -i 's/level: "info"/level: "debug"/' rhema-mcp.yaml

Test API

# Test all endpoints
 
 
curl http://localhost:8080/health
curl http://localhost:8080/info
curl http://localhost:8080/scopes
curl http://localhost:8080/stats

Load Testing

# Simple load test
 
 
for i in {1..100}; do
  curl -s http://localhost:8080/health > /dev/null &
done
wait
 
# Using hey (install with: go install github.com/rakyll/hey@latest)
 
 
hey -n 1000 -c 10 http://localhost:8080/health

Profile Performance

# CPU profiling
 
 
curl http://localhost:8080/debug/pprof/profile
 
# Memory profiling
 
 
curl http://localhost:8080/debug/pprof/heap
Last updated on
Rhema MCP Daemon Deployment GuideRhema MCP Daemon Usage Guide