🚀 Roblox MCP Node.js Server

Comprehensive MCP Server untuk Roblox Development - Solusi Node.js yang stabil dan siap produksi untuk semua kebutuhan Roblox development workflow.

✨ Key Features

🛠️ Complete Roblox Tool Suite (8 Tools)

• ✅ create_script - Create new Lua/Luau scripts
• ✅ list_scripts - List all scripts in project
• ✅ update_script - Update existing scripts
• ✅ delete_script - Delete scripts
• ✅ get_project_status - Get project statistics
• ✅ validate_script - Validate script syntax dan security
• ✅ backup_project - Create project backups
• ✅ restore_project - Restore from backups

🚀 Production Ready

• 📦 Built-in Client Library - Include client functionality dalam server package
• 🔐 HMAC Authentication - Secure API communication
• 🗄️ SQLite Database - Persistent script storage
• 🐳 Docker Deployment - Ready untuk containerization
• 🚂 Railway Deployment - Cloud deployment ready
• 📊 Comprehensive Logging - Full operation tracking
• ⚡ High Performance - Node.js + Express optimized

🛡️ Security & Reliability

• 🔒 Rate Limiting - Prevent abuse
• 🛡️ Security Headers - Helmet.js protection
• ✅ Input Validation - Joi schema validation
• 🔐 HMAC Signing - Request authenticity verification
• 🚨 Error Handling - Graceful failure recovery

🎮 Web Dashboard Interface

• 🌐 Modern Web Interface - Beautiful dashboard untuk manajemen semua tools
• 📱 Fully Responsive - Perfect di desktop, tablet, dan mobile
• 🎨 Professional Design - Dark/Light theme dengan smooth animations
• ⚡ Real-time Updates - Live data dan auto-refresh capabilities
• 📊 Analytics Dashboard - Charts dan insights untuk project monitoring
• 🔍 Advanced Search - Filter dan search scripts dengan mudah
• 💾 One-click Backup - Manajemen backup dan restore yang mudah
• 🔐 Secure Settings - Konfigurasi HMAC secret dengan interface yang user-friendly

🚀 Quick Start

Prerequisites

• Node.js 18+ installed
• npm atau yarn package manager

Installation

# Clone atau extract server files
cd roblox-mcp-nodejs

# Install dependencies
npm install

# Initialize database
npm run db:init

# Start server (development)
npm run dev

# Start server (production)
npm start

Basic Usage

🌐 Web Interface (Recommended)

# Start the server
npm start

# Buka browser dan navigasi ke:
http://localhost:3000

# Configure HMAC secret di Settings
# Enjoy the beautiful dashboard!

📡 API Testing

# Test dengan basic usage
node examples/basic-usage.js

# Test dengan advanced usage
node examples/advanced-usage.js

# Test dengan production usage
node examples/production-usage.js

🎮 Web Dashboard Features

Dashboard Sections:

• 📊 Overview - Project statistics dan quick actions
• 📝 Script Manager - Create, edit, delete scripts dengan interface yang modern
• 💾 Backup & Restore - One-click backup management
• 📈 Analytics - Visual charts dan insights

Key Benefits:

• ✅ No command-line experience required
• ✅ Real-time script preview dengan syntax highlighting
• ✅ Advanced search dan filtering
• ✅ Mobile-friendly responsive design
• ✅ Secure authentication configuration
• ✅ Beautiful animations dan micro-interactions

📖 Detailed Guide: Lihat Web Interface Guide untuk dokumentasi lengkap

🛠️ Available Tools

1. create_script

Create new Roblox scripts dengan validation

Parameters:

• name (str): Script name (unique identifier)
• content (str): Script content (Lua/Luau code)
• script_type (str, optional): 'lua' or 'luau' (default: 'lua')
• project_id (str, optional): Project identifier (default: 'default')

Example:

curl -X POST http://localhost:3000/api/create_script \
  -H "Content-Type: application/json" \
  -H "X-Signature: your_signature" \
  -d '{
    "name": "PlayerController",
    "content": "local Players = game:GetService(\"Players\")",
    "script_type": "lua",
    "project_id": "game_project_001"
  }'

2. list_scripts

List all scripts dalam project dengan metadata

Example:

curl -X GET "http://localhost:3000/api/list_scripts?project_id=default" \
  -H "X-Signature: your_signature"

3. update_script

Update existing script content

4. delete_script

Delete script from database

5. get_project_status

Get comprehensive project statistics dan health

6. validate_script

Validate script content untuk syntax, security, dan best practices

7. backup_project

Create complete project backup dengan metadata

8. restore_project

Restore project dari backup file

🚂 Railway Deployment

Prerequisites

1. GitHub repository dengan kode ini
2. Railway account di https://railway.app

Step-by-Step Deployment

1. Setup GitHub Repository

# Initialize git (jika belum)
git init
git add .
git commit -m "Initial commit: Roblox MCP Node.js Server"
git branch -M main
git remote add origin https://github.com/yourusername/roblox-mcp-nodejs.git
git push -u origin main

2. Deploy ke Railway

1. Login ke Railway (https://railway.app)
2. Click "New Project"
3. Select "Deploy from GitHub repo"
4. Choose repository roblox-mcp-nodejs
5. Click "Deploy Now"

3. Configure Environment Variables

Di Railway dashboard, pergi ke Variables tab dan add:

# Required Configuration
NODE_ENV=production
PORT=3000

# Database Configuration
DB_PATH=./data/roblox_mcp.db

# HMAC Security (CRITICAL - generate secure secret!)
ROBLOX_MCP_HMAC_SECRET=your_very_secure_hmac_secret_32_chars_minimum

# Logging
LOG_LEVEL=info
ROBLOX_MCP_VERBOSE=false

# Rate Limiting
ENABLE_RATE_LIMITING=true
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

# Security
ENABLE_SECURITY_HEADERS=true
CORS_ORIGIN=*

4. Custom Build Command (Optional)

Di Railway, pergi ke Settings > Build dan set:

Build Command: npm ci --only=production

5. Deploy

1. Click "Deploy" di Railway
2. Wait untuk deployment selesai (~2-3 menit)
3. Copy Public URL dari Railway dashboard
4. Test dengan: curl http://your-app.railway.app/health

Railway Configuration File (railway.json)

{
  "build": {
    "builder": "NIXPACKS"
  },
  "deploy": {
    "startCommand": "npm start",
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}

🐳 Docker Deployment

Local Docker Run

# Build image
docker build -f docker/Dockerfile -t roblox-mcp-server .

# Run container
docker run -p 3000:3000 \
  -e ROBLOX_MCP_HMAC_SECRET=your_hmac_secret \
  -v roblox_data:/app/data \
  roblox-mcp-server

Docker Compose (Recommended)

# Start services
docker-compose -f docker/docker-compose.yml up -d

# View logs
docker-compose -f docker/docker-compose.yml logs -f

# Stop services
docker-compose -f docker/docker-compose.yml down

⚙️ Configuration

Environment Variables

Variable	Required	Default	Description
NODE_ENV	No	development	Environment mode
PORT	No	3000	Server port
DB_PATH	No	./data/roblox_mcp.db	Database file path
ROBLOX_MCP_HMAC_SECRET	Yes	-	HMAC secret for authentication
ROBLOX_MCP_VERBOSE	No	false	Enable verbose logging
ENABLE_RATE_LIMITING	No	true	Enable rate limiting
RATE_LIMIT_WINDOW_MS	No	900000	Rate limit window in ms
RATE_LIMIT_MAX_REQUESTS	No	100	Max requests per window
LOG_LEVEL	No	info	Log level
CORS_ORIGIN	No	*	CORS origin

Example .env File

# Production Configuration
NODE_ENV=production
PORT=3000
DB_PATH=./data/roblox_mcp.db
ROBLOX_MCP_HMAC_SECRET=your_very_secure_production_secret_32_chars_minimum
ROBLOX_MCP_VERBOSE=false
ENABLE_RATE_LIMITING=true
LOG_LEVEL=info
CORS_ORIGIN=*

# Development Configuration  
NODE_ENV=development
ROBLOX_MCP_HMAC_SECRET=dev_secret_123
ROBLOX_MCP_VERBOSE=true
LOG_LEVEL=debug

📚 API Reference

Authentication

Semua API requests harus include HMAC signature:

const crypto = require('crypto');

function generateSignature(data, secret) {
  return crypto
    .createHmac('sha256', secret)
    .update(data, 'utf8')
    .digest('hex');
}

// Headers yang diperlukan:
'X-Signature': generatedSignature
'X-Timestamp': Date.now().toString()
'Content-Type': 'application/json'

Response Format

Success Response:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": { ... },
  "timestamp": "2025-11-03T10:08:05.000Z"
}

Error Response:

{
  "success": false,
  "error": "Error description",
  "code": "ERROR_CODE"
}

Health Check

GET /health

Response:

{
  "status": "healthy",
  "timestamp": "2025-11-03T10:08:05.000Z",
  "uptime": 1234,
  "memory": { ... },
  "version": "1.0.0"
}

🧪 Testing

Unit Tests

# Test all functionality
npm test

# Test specific functionality
node examples/basic-usage.js
node examples/advanced-usage.js
node examples/production-usage.js

API Testing

# Health check
curl http://localhost:3000/health

# Create script
curl -X POST http://localhost:3000/api/create_script \
  -H "Content-Type: application/json" \
  -H "X-Signature: your_signature" \
  -d '{"name":"test","content":"print(\"Hello\")"}'

# List scripts
curl -X GET "http://localhost:3000/api/list_scripts" \
  -H "X-Signature: your_signature"

🔧 Troubleshooting

Common Issues

1. Database Connection Error

Error: SQLITE_CANTOPEN: unable to open database file

Solution:

# Check database directory permissions
ls -la data/
# Fix permissions
chmod 755 data/
# Or specify full path
export DB_PATH=/full/path/to/roblox_mcp.db

2. HMAC Authentication Failed

Error: Invalid signature

Solution:

# Verify HMAC secret matches between client and server
echo "Client Secret: $ROBLOX_MCP_HMAC_SECRET"
echo "Server Secret: $(grep ROBLOX_MCP_HMAC_SECRET .env)"

# Ensure timestamp is recent (< 5 minutes)
const timestamp = Date.now(); // Should be current time

3. Port Already in Use

Error: listen EADDRINUSE :::3000

Solution:

# Kill process using port 3000
lsof -ti:3000 | xargs kill -9

# Or use different port
export PORT=3001

4. Permission Denied (Docker)

Error: EACCES: permission denied

Solution:

# Fix file permissions in container
docker exec -u root roblox-mcp-server chown -R roblox:nodejs /app
# Or mount with correct permissions
docker run -v $(pwd)/data:/app/data roblox-mcp-server

Debug Mode

# Enable debug logging
export LOG_LEVEL=debug
export ROBLOX_MCP_VERBOSE=true
npm start

Health Monitoring

# Monitor server health
watch -n 5 'curl -s http://localhost:3000/health | jq .'

# Monitor logs
tail -f logs/app.log

🏗️ Architecture

roblox-mcp-nodejs/
├── src/                       # Backend server
│   ├── server.js              # Main Express server
│   ├── database.js            # SQLite database service
│   ├── config.js              # Configuration management
│   ├── robloxToolsService.js  # Roblox tools implementation
│   └── client.js              # Built-in client library
├── public/                    # Web Interface (NEW!)
│   ├── index.html             # Main dashboard application
│   ├── css/                   # Modern UI styles
│   │   ├── style.css          # Core styling
│   │   ├── components.css     # Component styles
│   │   └── animations.css     # Smooth animations
│   ├── js/                    # Frontend JavaScript
│   │   ├── config.js          # App configuration
│   │   ├── api.js             # API communication
│   │   ├── ui.js              # UI management
│   │   ├── charts.js          # Analytics charts
│   │   └── main.js            # Main application
│   └── assets/                # Static resources
├── examples/                  # API usage examples
│   ├── basic-usage.js         # Basic functionality tests
│   ├── advanced-usage.js      # Advanced usage patterns
│   └── production-usage.js    # Production deployment tests
├── docs/                      # Documentation
│   ├── WEB-INTERFACE-GUIDE.md # Web interface documentation
│   └── RAILWAY-DEPLOYMENT.md  # Deployment guides
├── docker/                    # Docker configuration
│   ├── Dockerfile             # Container definition
│   ├── docker-compose.yml     # Multi-service setup
│   └── nginx/                 # Reverse proxy config
├── data/                      # Database files
├── logs/                      # Application logs
├── backups/                   # Project backups
├── package.json               # Dependencies
└── README.md                  # This file

🔄 Migration from Python Version

Untuk user yang migrasi dari Python version:

API Compatibility

API endpoints tetap sama, hanya base URL berubah:

# Python version
POST /tools/create_script

# Node.js version  
POST /api/create_script

Client Update

// Python MCP client
from roblox_mcp import create_script

// Node.js MCP client
const RobloxMCPClient = require('roblox-mcp-nodejs/src/client');
const client = new RobloxMCPClient(baseUrl, hmacSecret);
await client.createScript(name, content, scriptType, projectId);

Database Migration

Database structure tetap sama, tidak perlu migration.

🤝 Contributing

1. Fork repository
2. Create feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open Pull Request

📝 License

Distributed under the MIT License. See LICENSE for more information.

🆘 Support

• 📖 Documentation: Check this README
• 🧪 Testing: Run test suite sebelum deployment
• 🚀 Deployment: Follow Railway deployment guide
• 🐛 Issues: Report bugs dengan detailed reproduction steps

🏆 Acknowledgments

• Express.js - For the excellent web framework
• Node.js - For the powerful runtime environment
• SQLite - For reliable embedded database
• Roblox Development Community - For API insights and best practices
• MiniMax Agent - For comprehensive development and testing

---

Ready untuk production deployment! 🚀

Built dengan ❤️ untuk Roblox developers

Quick Links:

• 🎮 Web Interface Guide - Beautiful dashboard documentation
• 🚀 Railway Deployment Guide
• 🐳 Docker Setup
• 📚 API Documentation
• 🧪 Testing Guide