feat: MCP server for AI agent control

packages/docs/SUMMARY.md

@@ -12,6 +12,10 @@
 * [Dashboard](plugins/dashboard.md)
 * [Providers](plugins/providers.md)
 
+## Integrations
+
+* [MCP Server](integrations/mcp-server.md)
+
 ## Theming
 
 * [Themes](themes/themes.md)
@@ -21,6 +25,7 @@
 ## Development
 
 * [Logging](development/logging.md)
+* [MCP Architecture](development/mcp-architecture.md)
 
 ## Misc
 

packages/docs/development/mcp-architecture.md

@@ -0,0 +1,93 @@
+---
+description: How the MCP server works internally and how to extend it.
+---
+
+# MCP architecture
+
+Nuclear's [MCP](https://modelcontextprotocol.io/) 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`. No business logic lives in Rust. These tools reuse the same API as plugins.
+
+| 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: [...] } }` |
+
+The first three are discovery tools. Agents use them to figure out what's available before calling anything. The TS handler serves these from static metadata objects (`apiMeta` and `typeRegistry` from `@nuclearplayer/plugin-sdk/mcp`).
+
+The `call` tool runs through the dispatcher, which converts named parameters to positional arguments and calls the API method.
+
+## The Rust/JS bridge protocol
+
+Rust and JS communicate through Tauri's event system with a request/response pattern correlated by trace IDs.
+
+### Request flow
+
+1. An agent calls a tool. Rust receives the HTTP request.
+2. Rust generates a UUID trace ID, stores a `oneshot::Sender` in a `HashMap<String, Sender>`, and emits an `mcp:tool-call` event to the webview with `{ traceId, toolName, arguments }`.
+3. JS receives the event, validates the payload with Zod, and routes to the appropriate handler.
+4. For `list_methods`, `method_details`, and `describe_type`: JS looks up the answer in `apiMeta` or `typeRegistry`. No API call happens.
+5. For `call`: the dispatcher parses `"Queue.addToQueue"` into domain + method, looks up the `MethodMeta` to get the parameter order, converts the named params object into positional args, and calls the method on `NuclearPluginAPI`.
+6. JS calls `invoke('mcp_respond', { response: { traceId, success, data } })` (or `{ traceId, success: false, error }` on failure).
+7. Rust receives the `mcp_respond` command, looks up the trace ID in the pending map, and sends the response through the oneshot channel. The original `call_tool` function was awaiting this channel and now returns the result to the HTTP response.
+
+### Timeout and error handling
+
+The bridge times out after 30 seconds. If JS 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.
+- `ToolError`: 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.
+
+### Metadata types
+
+Defined in `meta.ts`:
+
+```typescript
+type ParamMeta = {
+  name: string;
+  type: string;
+};
+
+type MethodMeta = {
+  name: string;
+  description: string;
+  params: ParamMeta[];
+  returns: string;
+};
+
+type DomainMeta = {
+  description: string;
+  methods: Record<string, MethodMeta>;
+};
+```
+
+Each domain has a `*.meta.ts` file (e.g., `queue.meta.ts`) that exports a `DomainMeta` object. The `apiMeta` object in `meta.ts` aggregates all domain metadata by importing these files.
+
+The `typeRegistry` in `typeRegistry.ts` maps type names (like `"Track"`, `"QueueItem"`) to their field definitions so agents can call `describe_type` and understand the data shapes.
+
+## How to add a new domain
+
+1. Create the Host interface, host implementation, and API class following the standard plugin SDK pattern (see [adding new domains](../plugin-sdk/adding-domains.md)).
+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. Update the domain list in the `list_methods` tool description string in `packages/player/src-tauri/src/mcp/tools.rs`. This is the only Rust change needed when adding a domain.

packages/docs/integrations/mcp-server.md

@@ -0,0 +1,137 @@
+---
+description: Let AI agents control Nuclear via the Model Context Protocol.
+---
+
+# MCP server
+
+Nuclear includes a built-in [MCP](https://modelcontextprotocol.io/) server that lets your AI control the music player, doing pretty much anything that you can!
+
+## Enable the server
+
+1. Open Nuclear → Settings → Integrations.
+2. Toggle `Enable MCP Server` on.
+3. The server starts on `http://127.0.0.1:8800/mcp` (localhost only). If port 8800 is taken, it tries 8801, 8802, and so on up to 8809.
+4. The **MCP Server URL** field below the toggle shows the actual URL. Click the copy button to grab it.
+
+## Connect your AI tool
+
+The server URL is `http://127.0.0.1:8800/mcp` using the `Streamable HTTP` transport.
+
+{% tabs %}
+{% tab title="Claude Code" %}
+```bash
+claude mcp add nuclear --transport http http://127.0.0.1:8800/mcp
+```
+{% endtab %}
+
+{% tab title="OpenCode" %}
+Add to your `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "nuclear": {
+      "type": "remote",
+      "url": "http://127.0.0.1:8800/mcp"
+    }
+  }
+}
+```
+{% endtab %}
+
+{% tab title="Codex CLI" %}
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.nuclear]
+url = "http://127.0.0.1:8800/mcp"
+```
+
+Or via the CLI:
+
+```bash
+codex mcp add nuclear --url http://127.0.0.1:8800/mcp
+```
+{% endtab %}
+
+{% tab title="Claude Desktop / Cursor / Windsurf" %}
+Add to your MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "nuclear": {
+      "url": "http://127.0.0.1:8800/mcp"
+    }
+  }
+}
+```
+{% endtab %}
+
+{% tab title="MCP Inspector" %}
+```bash
+npx @modelcontextprotocol/inspector
+```
+
+Enter `http://127.0.0.1:8800/mcp` as the URL and select `Streamable HTTP` as the transport.
+{% endtab %}
+{% endtabs %}
+
+## Tools
+
+Nuclear exposes four MCP tools. The server uses a hierarchical discovery pattern: start broad, drill down, then act.
+
+### `list_methods`
+
+Lists available methods in a domain.
+
+| Parameter | Type   | Required | Description                                                                                                            |
+| --------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `domain`  | string | yes      | One of: `Queue`, `Playback`, `Metadata`, `Favorites`, `Playlists`, `Dashboard`, `Providers`. |
+
+Returns the method names and short descriptions for that domain.
+
+### `method_details`
+
+Gets full details for a single method: its description, parameter names and types, and return type.
+
+| Parameter | Type   | Required | Description                                                       |
+| --------- | ------ | -------- | ----------------------------------------------------------------- |
+| `method`  | string | yes      | The method name in `Domain.method` format, e.g. `Queue.addToQueue`. |
+
+### `describe_type`
+
+Gets the JSON shape of a data type. Use this when `method_details` returns a parameter or return type that references a complex type.
+
+| Parameter | Type   | Required | Description                                          |
+| --------- | ------ | -------- | ---------------------------------------------------- |
+| `type`    | string | yes      | The type name, e.g. `Track`, `QueueItem`, `Playlist`. |
+
+### `call`
+
+Calls a Nuclear API method.
+
+| Parameter | Type   | Required | Description                                                                                    |
+| --------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
+| `method`  | string | yes      | The method name in `Domain.method` format, e.g. `Queue.addToQueue`.                              |
+| `params`  | object | no       | A JSON object with named fields matching the method's parameters. Omit or pass `{}` for methods with no parameters. |
+
+## Discovery workflow
+
+An agent follows this sequence to find and call an API method:
+
+1. Read the `list_methods` tool description to see the seven available domains.
+2. Call `list_methods` with a domain (e.g. `Queue`) to see that domain's methods.
+3. Call `method_details` (e.g. `Queue.addToQueue`) to get parameter names, types, and the return type.
+4. If a parameter or return type is a complex type like `Track`, call `describe_type` to see its fields.
+5. Call `call` with the method name and parameters to execute it.
+
+Each step returns a small, focused payload to save on tokens.
+
+## Agent skill
+
+If your AI tool supports skills (like Claude Code), you can install one that teaches the agent how to use Nuclear's MCP tools, including the discovery workflow, common recipes, and the full API reference.
+
+[Download nuclear-mcp.zip](/skills/nuclear-mcp.zip)
+
+Unzip it into your skills directory (e.g. `~/.claude/skills/`) and the agent will pick it up automatically.

packages/i18n/src/locales/en_US.json

@@ -253,6 +253,19 @@
         "title": "Auto-install updates",
         "description": "Download and install updates automatically when available"
       }
+    },
+    "integrations": {
+      "title": "Integrations",
+      "mcp": {
+        "enabled": {
+          "title": "Enable MCP Server",
+          "description": "Start a local MCP server that allows AI tools to control Nuclear."
+        },
+        "serverUrl": {
+          "title": "MCP Server URL",
+          "description": "Point your AI tool to this URL to connect to Nuclear."
+        }
+      }
     }
   },
   "queue": {