MCP Server

Model Context Protocol adapter for Claude and Cursor integration

The MCP server is the interface layer that exposes RbxGenie tools to AI assistants like Claude Desktop and Cursor through the Model Context Protocol (MCP).

Overview

Location: src/mcp.ts

The MCP server is a stdio-based MCP implementation that:

1. Defines 50+ tools with Zod schema validation
2. Forwards tool calls to the Node.js daemon via HTTP
3. Translates responses back to MCP format for AI consumption

MCP is an open protocol developed by Anthropic that allows AI assistants to interact with external systems through a standardized tool interface. Learn more at modelcontextprotocol.io

Configuration

Location: src/mcp.ts:5-6

const DAEMON_URL = process.env.DAEMON_URL || "http://127.0.0.1:7766";
const TOOL_TIMEOUT_MS = 120_000;

Default URL

http://127.0.0.1:7766 — Standard daemon address

Override

Set DAEMON_URL environment variable to use a different daemon

{
  "mcpServers": {
    "rbxgenie": {
      "command": "node",
      "args": [".build/mcp.js"],
      "env": {
        "DAEMON_URL": "http://127.0.0.1:8080"
      }
    }
  }
}

Tool Definitions

Location: src/mcp.ts:8-80

Tools are defined with name, description, and Zod schema for argument validation:

interface ToolDef {
  name: string;
  description: string;
  schema: Record<string, z.ZodTypeAny>;
}

const TOOLS: ToolDef[] = [
  {
    name: "get_file_tree",
    description: "Get the file/instance tree of the place. Args: { root?: string, depth?: number }",
    schema: {
      root: z.string().optional(),
      depth: z.number().optional()
    }
  },
  {
    name: "set_property",
    description: "Set a property on an instance. Args: { path: string, property: string, value: any }",
    schema: {
      path: z.string(),
      property: z.string(),
      value: z.any()
    }
  },
  // ... 48 more tools
];

Tool Categories

The 50+ tools are organized into logical groups:

Instance / Info (11 tools)

• get_file_tree — Recursive instance tree
• search_files — Name pattern search
• get_place_info — PlaceId, version, creator info
• get_services — List all services
• search_objects — Multi-criteria search
• get_instance_properties — All properties of an instance
• get_instance_children — Direct children
• search_by_property — Find instances by property value
• get_class_info — Roblox class information
• get_project_structure — High-level structure
• summarize_game — Game summary

Properties (5 tools)

• set_property — Set single property
• mass_set_property — Set property on multiple instances
• mass_get_property — Get property from multiple instances
• set_calculated_property — Use expression for value
• set_relative_property — Relative adjustment

Objects (7 tools)

• create_object — Create single instance
• create_object_with_properties — Create with initial properties
• mass_create_objects — Create multiple instances
• mass_create_objects_with_properties — Batch create with properties
• delete_object — Delete instance
• smart_duplicate — Intelligent duplication
• mass_duplicate — Duplicate multiple instances

Scripts (5 tools)

• get_script_source — Read script source
• set_script_source — Replace entire source
• edit_script_lines — Edit line range
• insert_script_lines — Insert at line number
• delete_script_lines — Delete line range

Attributes (4 tools)

• get_attribute — Get single attribute
• set_attribute — Set attribute value
• get_attributes — Get all attributes
• delete_attribute — Remove attribute

Tags (4 tools)

• get_tags — Get tags on instance
• add_tag — Add CollectionService tag
• remove_tag — Remove tag
• get_tagged — Find all instances with tag

Selection (1 tool)

• get_selection — Get currently selected instances

Execute (3 tools)

• execute_luau — Run Luau code in edit mode
• get_console_output — Retrieve console logs
• clear_console_output — Clear log buffer

Playtest (5 tools)

• start_play — Enter play mode
• stop_play — Exit play mode
• run_server — Enter server mode
• get_studio_mode — Current mode
• run_script_in_play_mode — Automated test runner

Marketplace (1 tool)

• insert_model — Search and insert free models

HTTP Proxy

Location: src/mcp.ts:82-107

The MCP server forwards tool calls to the daemon via HTTP POST:

async function callDaemonTool(name: string, args: Record<string, unknown>): Promise<string> {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), TOOL_TIMEOUT_MS);

  try {
    const res = await fetch(`${DAEMON_URL}/tool/${name}`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(args),
      signal: controller.signal,
    });
    const data: any = await res.json();
    if (!data.ok) {
      const msg = data.error || "Unknown error";
      return JSON.stringify({ error: msg, timeout: data.timeout });
    }
    return typeof data.result === "string" ? data.result : JSON.stringify(data.result);
  } catch (err: any) {
    if (err.name === "AbortError") {
      return JSON.stringify({ error: "MCP proxy timeout", timeout: true });
    }
    throw err;
  } finally {
    clearTimeout(timer);
  }
}

1. AbortController Setup

   Create an AbortController with 120-second timeout

2. HTTP POST

   POST to /tool/{name} with JSON args

3. Error Handling

   If daemon returns ok: false, format error as JSON string

4. Timeout Handling

   If AbortController fires, return timeout error

5. Response Formatting

   Return result as string (JSON or plain text)

Server Registration

Location: src/mcp.ts:109-143

async function main() {
  const server = new McpServer({
    name: "RbxGenie",
    version: "1.0.0",
  });

  for (const def of TOOLS) {
    const shape = def.schema as Record<string, z.ZodTypeAny>;
    server.tool(
      def.name,
      def.description,
      shape,
      async (args: Record<string, unknown>) => {
        try {
          const result = await callDaemonTool(def.name, args);
          return { content: [{ type: "text" as const, text: result }] };
        } catch (err) {
          return {
            content: [{ type: "text" as const, text: `Error: ${String(err)}` }],
            isError: true,
          };
        }
      }
    );
  }

  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("[RbxGenie MCP] Server started on stdio");
}

main().catch((err) => {
  console.error("[RbxGenie MCP] Fatal:", err);
  process.exit(1);
});

The MCP server uses stdio transport, which means it communicates with the AI assistant via standard input/output. This is the standard transport for MCP servers.

Integration with AI Assistants

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "rbxgenie": {
      "command": "node",
      "args": ["/path/to/RbxGenie/.build/mcp.js"]
    }
  }
}

Cursor

Add to .cursorrules or Cursor settings:

{
  "mcp": {
    "servers": {
      "rbxgenie": {
        "command": "node",
        "args": ["/path/to/RbxGenie/.build/mcp.js"]
      }
    }
  }
}

OpenCode

Add to ~/.config/opencode/mcp.json:

{
  "mcpServers": {
    "rbxgenie": {
      "command": "node",
      "args": ["/path/to/RbxGenie/.build/mcp.js"]
    }
  }
}

Once configured, the AI assistant will automatically discover all 50+ RbxGenie tools and can use them in conversations.

Tool Response Format

All tools return text responses formatted for AI consumption:

Success Response

Simple text or JSON string:

Property set

or

{
  "name": "Part",
  "className": "Part",
  "children": [
    { "name": "Mesh", "className": "SpecialMesh" }
  ]
}

Error Response

JSON with error field:

{
  "error": "Path not found at segment [2] 'Part' in 'Workspace.Part'"
}

Timeout Response

{
  "error": "MCP proxy timeout",
  "timeout": true
}

The MCP server always returns content: [{ type: "text", text: "..." }] format. Complex data structures are JSON-stringified for the AI to parse.

Error Propagation

Errors flow through multiple layers:

1. Plugin Error

   Lua error or validation failure in tool execution

2. Bridge Error

   Posted to /result with error field

3. Daemon Error

   Returned as { ok: false, error: "..." } in HTTP response

4. MCP Proxy Error

   Formatted as JSON string with error field

5. MCP Response Error

   Returned with isError: true flag to AI assistant

The AI assistant receives errors as text responses. It’s responsible for parsing error JSON and determining how to handle failures (retry, report to user, etc.).

Debugging

The MCP server logs to stderr (visible in AI assistant logs):

console.error("[RbxGenie MCP] Server started on stdio");
console.error("[RbxGenie MCP] Fatal:", err);

Check the AI assistant’s logs for MCP server errors:

Claude Desktop:

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\mcp*.log

Cursor:

• Check Cursor’s developer console (Help → Toggle Developer Tools)

OpenCode:

• Run OpenCode with DEBUG=mcp environment variable

Schema Validation

Zod schemas validate arguments before forwarding to daemon:

{
  name: "set_property",
  schema: {
    path: z.string(),        // Required string
    property: z.string(),    // Required string
    value: z.any()           // Any type
  }
}

If the AI provides invalid arguments (wrong type, missing required field), the MCP SDK automatically returns a validation error before the daemon is called.

Performance Characteristics

Startup Time

~100-200ms — Node.js startup + MCP SDK initialization

Tool Call Latency

50-200ms typical (network + daemon + plugin)
Up to 120s for timeouts

Concurrent Tools

Multiple tool calls execute sequentially in the plugin
MCP server handles concurrent requests from AI

Memory Usage

~20-40 MB for Node.js + MCP SDK

Security Considerations

The MCP server trusts the AI assistant and forwards all tool calls to the daemon without additional authentication. Only use RbxGenie with trusted AI assistants in local development environments.

Security model:

1. No network exposure — Daemon binds to localhost only
2. No authentication — Assumes single-user local machine
3. Full Studio access — execute_luau can run arbitrary code
4. AI trust boundary — AI assistant must be trusted

Do not expose the daemon port (7766) to the network. Do not run RbxGenie on shared machines or production environments.

Next Steps

Architecture Overview

Understand the complete system architecture

MCP Integration

Learn how to configure MCP for your AI assistant