# Roblox Studio MCP to Notion Bridge

This project solves the architectural incompatibility between the official **Roblox Studio MCP (Model Context Protocol)** and stateless cloud agents (like **Notion AI**).

## ⚠️ The Problem

The official Roblox Studio MCP runs locally as a `stdio` executable (`StudioMCP.exe`). 
Tools like Cursor or local Claude apps connect to it directly via child processes. They keep the connection open forever, which maintains the "Active Studio" state.

However, cloud-based agents like Notion communicate over HTTP/SSE. Notion connects, executes a tool, and drops the connection. When it reconnects, it spins up a *new* local MCP process that has forgotten which Studio instance is active. Because of this, trying to use `supergateway` out-of-the-box results in crashes, lost state, and the inability to execute complex tasks like getting the DataModel tree.

## 🛠️ The Solution

This bridge creates a **Persistent Multiplexer**.
1. `mcp-server.js` launches a **single, global** instance of `StudioMCP.exe` in the background and keeps it alive forever.
2. It listens for incoming transient SSE connections from the cloud (Notion).
3. It intercepts and filters out unsolicited `notifications/tools/list_changed` events that otherwise cause Notion's MCP client to crash.
4. `proxy.js` adds a layer of Bearer Token authentication so you can safely expose the bridge to the public internet via a tunnel.

## 🚀 Setup Instructions

### 1. Installation
Clone this repository and install the dependencies:
```bash
npm install
```

### 2. Configuration
Copy the `.env.example` file to `.env`:
```bash
cp .env.example .env
```
Open `.env` and fill in your details:
- `PUBLIC_URL`: The public HTTPS URL where your tunnel is hosted (e.g. `https://roblox.your-domain.com`). This is required so the SSE endpoint can tell Notion where to send POST messages.
- `AUTH_TOKEN`: Create a secure, random string (e.g. `my-super-secret-token-123`).

### 3. Start the Bridge
Run the launcher script:
```bash
start-bridge.bat
```
This will open two terminal windows: one for the MCP Server (Port 8000) and one for the Auth Proxy (Port 8001).

### 4. Create a Tunnel
You must expose Port **8001** to the internet. You can use Cloudflare Tunnels, ngrok, or a reverse SSH tunnel. 
Example using Cloudflare:
```bash
cloudflared tunnel --url http://localhost:8001
```

### 5. Connect Notion (Standard Chat Workflow)
**You do NOT need to use "Custom Agents"** (which consume expensive credits). You can connect this MCP server directly to a **standard Notion AI chat**!

Simply open a new standard chat in Notion and paste the following text:

```text
Connect to my Roblox Studio MCP tunnel using this data:
MCP URL: https://<YOUR_TUNNEL_URL>/sse
Auth method: Bearer Token
Token: <YOUR_AUTH_TOKEN>
Transport: SSE
```

Notion will automatically display a connection window. Confirm the details, and the standard Notion AI will instantly connect to your local Roblox Studio and gain access to the full suite of tools (reading/writing scripts, exploring the DataModel, etc.)!

### 6. Agent Instructions Prompt
To ensure the AI knows how to work with your Studio, send it this prompt after connecting:

```markdown
You are an expert Roblox Studio assistant. You are connected to my local Roblox Studio via an MCP SSE Bridge.

**Initialization Check:**
If you do not see advanced tools like `get_tree` or `execute_script`, it means the server needs to be initialized. In that case:
1. Call `list_roblox_studios` to find the active studio ID.
2. Call `set_active_studio` with that ID.
3. Stop and ask me to reply "continue" so your tools refresh.

**Workflow:**
- Always inspect the DataModel (`get_tree`) and read scripts before proposing changes.
- Prefer small, targeted code edits. Preserve existing architecture and naming conventions.
- Never make destructive changes without asking first.
- If a test cannot be executed via MCP, suggest specific Studio play-test steps.
```

Enjoy seamless, cloud-based Roblox game development directly in Notion!