MCP Architecture

How the MCP server works internally and how to extend it.

Nuclear's MCP server lets your AI control the music player and do anything that plugins can do!

The server runs on localhost:8800/mcp using the Streamable HTTP transport.

The four MCP tools

Rust defines four tools in tools.rs. Three are discovery tools that return metadata directly from Rust. The fourth, call, goes through a Rust-Typescript IPC bridge to execute methods in TypeScript.

Tool	Purpose	Arguments
list_methods	List methods in a domain	{ domain: "Queue" }
method_details	Get parameter names, types, return type for a method	{ method: "Queue.addToQueue" }
describe_type	Get the JSON shape of a data type (Track, QueueItem, etc.)	{ type: "Track" }
call	Execute a method	{ method: "Queue.addToQueue", params: { tracks: [...] } }

Discovery tools

list_methods, method_details, and describe_type are handled entirely in Rust. All API metadata (domain listings, method signatures, type shapes) is inlined in mcp/metadata.rs as static JSON.

The IPC bridge

Nuclear has a generic Rust-to-TypeScript bridge that the MCP server uses as an adapter. The bridge lives in src-tauri/src/bridge/ (Rust) and src/services/bridge/ (TypeScript).

How call works

1. An agent calls the call tool. Rust receives the HTTP request.

2. The MCP server passes the method name and params to Bridge::call().

3. The bridge generates a UUID trace ID, stores a oneshot::Sender in a pending map, and emits a bridge:request event to the webview with { traceId, method, params }.

4. TypeScript receives the event, validates the payload with Zod, and passes it to the bridge dispatcher.

5. The dispatcher parses "Queue.addToQueue" into domain + method, looks up the MethodMeta (from apiMeta in the plugin SDK) to get the parameter order, converts named params to positional args, and calls the method on NuclearPluginAPI.

6. TypeScript calls invoke('bridge_respond', { response: { traceId, status: 'success', data } }) (or { traceId, status: 'error', error } on failure).

7. The bridge looks up the trace ID in the pending map and sends the response through the oneshot channel back to the original call.

Timeout and error handling

The bridge times out after 30 seconds. If TypeScript doesn't respond in that window, Rust removes the pending entry and returns an error.

There are two error types:

• InfrastructureError: The bridge itself broke. Timeout, channel closed, event emission failed. Rust logs the error and returns it as an MCP protocol error (internal error). This means something is wrong with the bridge, not with the requested operation.

• HandlerError: The method ran but returned an error (e.g., "unknown domain", "playlist not found"). Rust passes this through as tool error content, which the agent can read and react to.

Server lifecycle

mcp_start and mcp_stop are Tauri commands (not events), so the JS caller gets a Result back and can handle errors.

Startup

MCP tries to bind to localhost:8800 by default, but if that port is taken, it tries the next one up, up to 8809. If all are taken, it returns an error.

Settings

The server can be disabled or enabled in the settings, and shows you its URL.

How to add a new domain

1. Create the host interface, host implementation, and API class following the host pattern.

2. Create a yourdomain.meta.ts file in packages/plugin-sdk/src/mcp/ exporting a DomainMeta.

3. Import and register it in the apiMeta object in packages/plugin-sdk/src/mcp/meta.ts.

4. Add the domain's methods and types to packages/player/src-tauri/src/mcp/metadata.rs so discovery tools can serve them.

5. Update the domain list in the list_methods tool description string in packages/player/src-tauri/src/mcp/tools.rs.