@mixofreality/live-mcp 1.0.0

package/dist/__tests__/bridge-client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/bridge-client.test.js

@@ -0,0 +1,110 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as net from 'node:net';
+import { BridgeClient } from '../bridge-client.js';
+describe('BridgeClient', () => {
+    let mockServer;
+    let serverPort;
+    beforeEach(async () => {
+        mockServer = net.createServer();
+        await new Promise((resolve) => {
+            mockServer.listen(0, '127.0.0.1', () => resolve());
+        });
+        const addr = mockServer.address();
+        serverPort = addr.port;
+    });
+    afterEach(async () => {
+        await new Promise((resolve) => {
+            mockServer.close(() => resolve());
+        });
+    });
+    it('should connect to the bridge server', async () => {
+        const serverGotConnection = new Promise((resolve) => {
+            mockServer.on('connection', () => resolve());
+        });
+        const client = new BridgeClient('127.0.0.1', serverPort);
+        await client.connect();
+        await serverGotConnection;
+        expect(client.isConnected()).toBe(true);
+        await client.disconnect();
+    });
+    it('should send a request and receive a response', async () => {
+        mockServer.on('connection', (socket) => {
+            let buffer = '';
+            socket.on('data', (data) => {
+                buffer += data.toString();
+                const lines = buffer.split('\n');
+                buffer = lines.pop();
+                for (const line of lines) {
+                    if (line.trim()) {
+                        const req = JSON.parse(line);
+                        const response = JSON.stringify({ id: req.id, result: { value: 120 } });
+                        socket.write(response + '\n');
+                    }
+                }
+            });
+        });
+        const client = new BridgeClient('127.0.0.1', serverPort);
+        await client.connect();
+        const result = await client.request('get_property', {
+            path: 'live_set',
+            property: 'tempo',
+        });
+        expect(result).toEqual({ value: 120 });
+        await client.disconnect();
+    });
+    it('should handle bridge error responses', async () => {
+        mockServer.on('connection', (socket) => {
+            let buffer = '';
+            socket.on('data', (data) => {
+                buffer += data.toString();
+                const lines = buffer.split('\n');
+                buffer = lines.pop();
+                for (const line of lines) {
+                    if (line.trim()) {
+                        const req = JSON.parse(line);
+                        const response = JSON.stringify({
+                            id: req.id,
+                            error: { code: -1, message: 'Object not found' },
+                        });
+                        socket.write(response + '\n');
+                    }
+                }
+            });
+        });
+        const client = new BridgeClient('127.0.0.1', serverPort);
+        await client.connect();
+        await expect(client.request('get_property', { path: 'live_set tracks 99', property: 'name' })).rejects.toThrow('Object not found');
+        await client.disconnect();
+    });
+    it('should emit notifications for property changes', async () => {
+        mockServer.on('connection', (socket) => {
+            setTimeout(() => {
+                const notification = JSON.stringify({
+                    notification: 'property_changed',
+                    subscriptionId: 'sub-1',
+                    path: 'live_set',
+                    property: 'tempo',
+                    value: 140,
+                });
+                socket.write(notification + '\n');
+            }, 50);
+        });
+        const client = new BridgeClient('127.0.0.1', serverPort);
+        await client.connect();
+        const notification = await new Promise((resolve) => {
+            client.onNotification((n) => resolve(n));
+        });
+        expect(notification).toEqual({
+            notification: 'property_changed',
+            subscriptionId: 'sub-1',
+            path: 'live_set',
+            property: 'tempo',
+            value: 140,
+        });
+        await client.disconnect();
+    });
+    it('should report disconnected when not connected', () => {
+        const client = new BridgeClient('127.0.0.1', 0);
+        expect(client.isConnected()).toBe(false);
+    });
+});

package/dist/bridge-client.d.ts

@@ -0,0 +1,16 @@
+import type { BridgeMethod, BridgeRequestParams, BridgeNotification, BridgeResult } from '@mixofreality/max4live-nodescript-ts';
+export declare class BridgeClient {
+    private readonly host;
+    private readonly port;
+    private socket;
+    private buffer;
+    private pending;
+    private notificationListeners;
+    constructor(host: string, port: number);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    request(method: BridgeMethod, params: BridgeRequestParams): Promise<BridgeResult>;
+    onNotification(listener: (notification: BridgeNotification) => void): void;
+    private handleData;
+}

package/dist/bridge-client.js

@@ -0,0 +1,91 @@
+import * as net from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { isBridgeNotification } from '@mixofreality/max4live-nodescript-ts';
+export class BridgeClient {
+    host;
+    port;
+    socket = null;
+    buffer = '';
+    pending = new Map();
+    notificationListeners = [];
+    constructor(host, port) {
+        this.host = host;
+        this.port = port;
+    }
+    async connect() {
+        return new Promise((resolve, reject) => {
+            const socket = net.createConnection({ host: this.host, port: this.port });
+            socket.once('connect', () => {
+                this.socket = socket;
+                resolve();
+            });
+            socket.once('error', reject);
+            socket.on('data', (data) => this.handleData(data.toString()));
+            socket.on('close', () => {
+                this.socket = null;
+                for (const [, { reject: rej }] of this.pending) {
+                    rej(new Error('Bridge connection closed'));
+                }
+                this.pending.clear();
+            });
+        });
+    }
+    async disconnect() {
+        if (this.socket) {
+            return new Promise((resolve) => {
+                this.socket.end(() => resolve());
+            });
+        }
+    }
+    isConnected() {
+        return this.socket !== null && !this.socket.destroyed;
+    }
+    async request(method, params) {
+        if (!this.isConnected()) {
+            throw new Error('Not connected to bridge');
+        }
+        const id = randomUUID();
+        const request = JSON.stringify({ id, method, params });
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.socket.write(request + '\n');
+        });
+    }
+    onNotification(listener) {
+        this.notificationListeners.push(listener);
+    }
+    handleData(data) {
+        this.buffer += data;
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop();
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (isBridgeNotification(msg)) {
+                for (const listener of this.notificationListeners) {
+                    listener(msg);
+                }
+            }
+            else {
+                const response = msg;
+                const pendingReq = this.pending.get(response.id);
+                if (pendingReq) {
+                    this.pending.delete(response.id);
+                    if (response.error) {
+                        pendingReq.reject(new Error(response.error.message));
+                    }
+                    else if (response.result) {
+                        pendingReq.resolve(response.result);
+                    }
+                }
+            }
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// MCP server entry point
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { BridgeClient } from './bridge-client.js';
+import { registerAllTools } from './tools/index.js';
+const BRIDGE_HOST = process.env['LIVE_MCP_BRIDGE_HOST'] ?? '127.0.0.1';
+const BRIDGE_PORT = parseInt(process.env['LIVE_MCP_BRIDGE_PORT'] ?? '19740', 10);
+const server = new McpServer({
+    name: 'live-mcp',
+    version: '1.0.0',
+}, {
+    capabilities: { logging: {} },
+});
+const bridge = new BridgeClient(BRIDGE_HOST, BRIDGE_PORT);
+registerAllTools(server, bridge);
+async function main() {
+    try {
+        await bridge.connect();
+        console.error('Connected to M4L bridge');
+    }
+    catch {
+        console.error(`Warning: Could not connect to M4L bridge at ${BRIDGE_HOST}:${BRIDGE_PORT}. Tools will fail until bridge is available.`);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Live MCP Server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/tools/call-function.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BridgeClient } from '../bridge-client.js';
+export declare function registerCallFunction(server: McpServer, bridge: BridgeClient): void;

package/dist/tools/call-function.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+export function registerCallFunction(server, bridge) {
+    server.registerTool('call_function', {
+        title: 'Call LOM Function',
+        description: 'Call a function on a Live Object Model object. Args is an optional JSON array string (e.g. "[1, 2]").',
+        inputSchema: {
+            path: z.string().describe('LOM path (e.g. "live_set tracks 0")'),
+            function: z.string().describe('Function name (e.g. "fire", "stop")'),
+            args: z
+                .string()
+                .optional()
+                .describe('Arguments as JSON array string (e.g. "[1, \\"hello\\"]")'),
+        },
+    }, async ({ path, function: fn, args }) => {
+        try {
+            const parsedArgs = args
+                ? JSON.parse(args)
+                : undefined;
+            const result = await bridge.request('call_function', {
+                path: path,
+                function: fn,
+                args: parsedArgs,
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+        }
+    });
+}

package/dist/tools/get-children.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BridgeClient } from '../bridge-client.js';
+export declare function registerGetChildren(server: McpServer, bridge: BridgeClient): void;

package/dist/tools/get-children.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export function registerGetChildren(server, bridge) {
+    server.registerTool('get_children', {
+        title: 'Get LOM Children',
+        description: 'List the children of a Live Object Model object. Returns child paths for navigation.',
+        inputSchema: {
+            path: z.string().describe('LOM path (e.g. "live_set", "live_set tracks 0")'),
+        },
+    }, async ({ path }) => {
+        try {
+            const result = await bridge.request('get_children', {
+                path: path,
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+        }
+    });
+}

package/dist/tools/get-property.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BridgeClient } from '../bridge-client.js';
+export declare function registerGetProperty(server: McpServer, bridge: BridgeClient): void;

package/dist/tools/get-property.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export function registerGetProperty(server, bridge) {
+    server.registerTool('get_property', {
+        title: 'Get LOM Property',
+        description: 'Read a property from a Live Object Model object. Use LOM paths like "live_set", "live_set tracks 0", "live_set tracks 0 devices 1 parameters 2".',
+        inputSchema: {
+            path: z.string().describe('LOM path (e.g. "live_set tracks 0")'),
+            property: z.string().describe('Property name (e.g. "tempo", "name")'),
+        },
+    }, async ({ path, property }) => {
+        try {
+            const result = await bridge.request('get_property', {
+                path: path,
+                property,
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+        }
+    });
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BridgeClient } from '../bridge-client.js';
+export declare function registerAllTools(server: McpServer, bridge: BridgeClient): void;

package/dist/tools/index.js

@@ -0,0 +1,14 @@
+import { registerGetProperty } from './get-property.js';
+import { registerSetProperty } from './set-property.js';
+import { registerCallFunction } from './call-function.js';
+import { registerGetChildren } from './get-children.js';
+import { registerObserve } from './observe.js';
+import { registerUnobserve } from './unobserve.js';
+export function registerAllTools(server, bridge) {
+    registerGetProperty(server, bridge);
+    registerSetProperty(server, bridge);
+    registerCallFunction(server, bridge);
+    registerGetChildren(server, bridge);
+    registerObserve(server, bridge);
+    registerUnobserve(server, bridge);
+}

package/dist/tools/observe.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BridgeClient } from '../bridge-client.js';
+export declare function registerObserve(server: McpServer, bridge: BridgeClient): void;

package/dist/tools/observe.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export function registerObserve(server, bridge) {
+    server.registerTool('observe', {
+        title: 'Observe LOM Property',
+        description: 'Subscribe to changes on a Live Object Model property. Returns a subscriptionId for later unobserve.',
+        inputSchema: {
+            path: z.string().describe('LOM path (e.g. "live_set tracks 0")'),
+            property: z.string().describe('Property name to observe (e.g. "tempo", "name")'),
+        },
+    }, async ({ path, property }) => {
+        try {
+            const result = await bridge.request('observe', {
+                path: path,
+                property,
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+        }
+    });
+}

package/dist/tools/set-property.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BridgeClient } from '../bridge-client.js';
+export declare function registerSetProperty(server: McpServer, bridge: BridgeClient): void;

package/dist/tools/set-property.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+export function registerSetProperty(server, bridge) {
+    server.registerTool('set_property', {
+        title: 'Set LOM Property',
+        description: 'Set a property on a Live Object Model object. The value should be a JSON string that will be parsed (e.g. "120.0", "\\"hello\\"", "true").',
+        inputSchema: {
+            path: z.string().describe('LOM path (e.g. "live_set tracks 0")'),
+            property: z.string().describe('Property name (e.g. "tempo", "name")'),
+            value: z.string().describe('Value as JSON string (e.g. "120.0", "\\"hello\\"", "true")'),
+        },
+    }, async ({ path, property, value }) => {
+        try {
+            const parsed = JSON.parse(value);
+            const result = await bridge.request('set_property', {
+                path: path,
+                property,
+                value: parsed,
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+        }
+    });
+}

package/dist/tools/unobserve.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BridgeClient } from '../bridge-client.js';
+export declare function registerUnobserve(server: McpServer, bridge: BridgeClient): void;

package/dist/tools/unobserve.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+export function registerUnobserve(server, bridge) {
+    server.registerTool('unobserve', {
+        title: 'Unobserve LOM Property',
+        description: 'Unsubscribe from a previously observed Live Object Model property using its subscriptionId.',
+        inputSchema: {
+            subscriptionId: z.string().describe('Subscription ID returned from observe'),
+        },
+    }, async ({ subscriptionId }) => {
+        try {
+            const result = await bridge.request('unobserve', { subscriptionId });
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+        }
+    });
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@mixofreality/live-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "live-mcp": "./dist/index.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "node --watch dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "npm run typecheck && npm run test",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "keywords": ["mcp", "ableton", "live", "max4live", "lom"],
+  "license": "MIT",
+  "description": "MCP server for controlling Ableton Live via the Live Object Model",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.16",
+    "@types/node": "^22.0.0",
+    "@mixofreality/max4live-nodescript-ts": "file:../../../shared/max4live-nodescript-ts"
+  }
+}