Development Setup

​

Prerequisites

• Node.js (v20 or higher)
• npm (comes with Node.js)
• Git for cloning the repository
• Roblox Studio installed

​

Clone the Repository

git clone https://github.com/boshyxd/robloxstudio-mcp.git
cd robloxstudio-mcp

​

Install Dependencies

npm install

• MCP SDK for Model Context Protocol support
• Express and CORS for HTTP server
• TypeScript and build tools
• Development dependencies (ESLint, Jest, etc.)

​

Development Workflow

​

Run the Development Server

npm run dev

• Runs the TypeScript source directly using tsx
• Enables hot module reloading
• Starts the HTTP bridge on port 3002
• Provides real-time debugging output

​

Build for Production

npm run build

• dist/index.js - Main MCP server
• dist/http-server.js - HTTP bridge server
• dist/bridge-service.js - Request queue manager
• dist/tools/ - MCP tool implementations

​

Run the Built Server

npm start

​

Project Structure

robloxstudio-mcp/
├── src/                      # TypeScript source files
│   ├── index.ts             # MCP server entry point
│   ├── http-server.ts       # HTTP bridge implementation
│   ├── bridge-service.ts    # Request/response queue
│   └── tools/               # MCP tool definitions
│       ├── index.ts         # Tool registry
│       └── studio-client.ts # Studio API client
├── dist/                    # Compiled JavaScript (generated)
├── studio-plugin/           # Roblox Studio plugin
│   ├── plugin.luau         # Main plugin script
│   ├── plugin.json         # Plugin metadata
│   ├── MCPPlugin.rbxmx     # Plugin package
│   └── INSTALLATION.md     # Plugin install guide
├── package.json            # npm configuration & scripts
├── tsconfig.json           # TypeScript configuration
└── README.md              # Project documentation

​

Key Directories

​

src/

• Entry point: Exposes 37+ tools via MCP stdio protocol
• HTTP bridge: Communicates with Roblox Studio plugin
• Tool implementations: File system, properties, scripting, etc.

​

dist/

• Ready for production deployment
• Used by npm start command
• Included in npm package distribution

​

studio-plugin/

• Polls HTTP server for pending requests
• Executes Studio API calls
• Returns data to MCP server

​

Code Quality Tools

​

Linting

npm run lint

• TypeScript best practices
• Code style consistency
• Potential bugs and errors

​

Type Checking

npm run typecheck

• Type errors
• Invalid type assignments
• Missing type definitions

​

Next Steps

​

Common Development Tasks

​

Clean Build

rm -rf dist/
npm run build

​

Watch Mode for Testing

npm run test:watch

​

Update Dependencies

npm outdated
npm update

​

Troubleshooting

​

Port Already in Use

# Find process using port 3002
lsof -i :3002

# Kill the process
kill -9 <PID>

HTTP_SERVER_PORT=3003 npm run dev

​

TypeScript Errors

1. Ensure you’re using Node.js v20+
2. Delete node_modules and reinstall:
   rm -rf node_modules package-lock.json
   npm install
   
3. Check TypeScript version:
   npx tsc --version
   

​

Plugin Not Connecting

1. Verify the dev server is running
2. Check that HTTP requests are enabled in Studio
3. Confirm the plugin is using the correct URL (localhost:3002)
4. Check firewall settings