@gtkx/mcp 0.18.1 → 0.18.2

package/src/connection-manager.ts

@@ -0,0 +1,247 @@
+import EventEmitter from "node:events";
+import {
+    appNotFoundError,
+    invalidRequestError,
+    ipcTimeoutError,
+    McpError,
+    type McpErrorCode,
+    noAppConnectedError,
+} from "./protocol/errors.js";
+import { type AppInfo, type IpcRequest, type IpcResponse, RegisterParamsSchema } from "./protocol/types.js";
+import type { AppConnection, SocketServer } from "./socket-server.js";
+
+type ConnectionManagerEventMap = {
+    appRegistered: [AppInfo];
+    appUnregistered: [string];
+};
+
+type PendingRequest = {
+    resolve: (result: unknown) => void;
+    reject: (error: Error) => void;
+    timeout: NodeJS.Timeout;
+};
+
+type RegisteredApp = {
+    info: AppInfo;
+    connection: AppConnection;
+};
+
+/**
+ * Manages connections between the MCP server and GTKX applications.
+ *
+ * Handles app registration, request routing, and connection lifecycle.
+ */
+export class ConnectionManager extends EventEmitter<ConnectionManagerEventMap> {
+    private static readonly DEFAULT_WAIT_TIMEOUT = 10000;
+
+    private apps: Map<string, RegisteredApp> = new Map();
+    private connectionToApp: Map<string, string> = new Map();
+    private pendingRequests: Map<string, PendingRequest> = new Map();
+    private requestTimeout: number;
+
+    constructor(
+        private socketServer: SocketServer,
+        options: { requestTimeout?: number } = {},
+    ) {
+        super();
+        this.requestTimeout = options.requestTimeout ?? 30000;
+
+        this.socketServer.on("request", (connection, request) => {
+            this.handleRequest(connection, request);
+        });
+
+        this.socketServer.on("response", (_connection, response) => {
+            this.handleResponse(response);
+        });
+
+        this.socketServer.on("disconnection", (connection) => {
+            this.handleDisconnection(connection);
+        });
+    }
+
+    getApps(): AppInfo[] {
+        return Array.from(this.apps.values()).map((app) => app.info);
+    }
+
+    getApp(appId: string): AppInfo | undefined {
+        return this.apps.get(appId)?.info;
+    }
+
+    hasConnectedApps(): boolean {
+        return this.apps.size > 0;
+    }
+
+    getDefaultApp(): RegisteredApp | undefined {
+        const first = this.apps.values().next();
+        return first.done ? undefined : first.value;
+    }
+
+    /**
+     * Waits for at least one app to connect and register.
+     *
+     * @param timeout - Maximum time to wait in milliseconds (default: 10000)
+     * @returns Promise that resolves with the first registered app info
+     * @throws Error if timeout is reached before any app registers
+     */
+    waitForApp(timeout: number = ConnectionManager.DEFAULT_WAIT_TIMEOUT): Promise<AppInfo> {
+        const defaultApp = this.getDefaultApp();
+        if (defaultApp) {
+            return Promise.resolve(defaultApp.info);
+        }
+
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                this.off("appRegistered", onRegister);
+                reject(
+                    new Error(
+                        `Timeout waiting for app registration after ${timeout}ms. ` +
+                            "Make sure your GTKX app is running with 'gtkx dev'.",
+                    ),
+                );
+            }, timeout);
+
+            const onRegister = (appInfo: AppInfo) => {
+                clearTimeout(timeoutId);
+                this.off("appRegistered", onRegister);
+                resolve(appInfo);
+            };
+
+            this.on("appRegistered", onRegister);
+        });
+    }
+
+    async sendToApp<T>(appId: string | undefined, method: string, params?: unknown): Promise<T> {
+        const app = appId ? this.apps.get(appId) : this.getDefaultApp();
+
+        if (!app) {
+            if (appId) {
+                throw appNotFoundError(appId);
+            }
+            throw noAppConnectedError();
+        }
+
+        const requestId = crypto.randomUUID();
+        const request: IpcRequest = {
+            id: requestId,
+            method,
+            params,
+        };
+
+        return new Promise<T>((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pendingRequests.delete(requestId);
+                reject(ipcTimeoutError(this.requestTimeout));
+            }, this.requestTimeout);
+
+            this.pendingRequests.set(requestId, {
+                resolve: resolve as (result: unknown) => void,
+                reject,
+                timeout,
+            });
+
+            const sent = this.socketServer.send(app.connection.id, request);
+            if (!sent) {
+                clearTimeout(timeout);
+                this.pendingRequests.delete(requestId);
+                reject(appNotFoundError(app.info.appId));
+                return;
+            }
+        });
+    }
+
+    cleanup(): void {
+        for (const pending of this.pendingRequests.values()) {
+            clearTimeout(pending.timeout);
+            pending.reject(new Error("Connection manager shutting down"));
+        }
+        this.pendingRequests.clear();
+    }
+
+    private handleRequest(connection: AppConnection, request: IpcRequest): void {
+        if (request.method === "app.register") {
+            this.handleRegister(connection, request);
+            return;
+        }
+
+        if (request.method === "app.unregister") {
+            this.handleUnregister(connection, request);
+            return;
+        }
+    }
+
+    private handleResponse(response: IpcResponse): void {
+        const pending = this.pendingRequests.get(response.id);
+        if (!pending) {
+            return;
+        }
+
+        clearTimeout(pending.timeout);
+        this.pendingRequests.delete(response.id);
+
+        if (response.error) {
+            const err = response.error;
+            pending.reject(new McpError(err.code as McpErrorCode, err.message, err.data));
+        } else {
+            pending.resolve(response.result);
+        }
+    }
+
+    private handleRegister(connection: AppConnection, request: IpcRequest): void {
+        const parseResult = RegisterParamsSchema.safeParse(request.params);
+        if (!parseResult.success) {
+            const response: IpcResponse = {
+                id: request.id,
+                error: invalidRequestError(parseResult.error.message).toIpcError(),
+            };
+            this.socketServer.send(connection.id, response);
+            return;
+        }
+
+        const params = parseResult.data;
+        const appInfo: AppInfo = {
+            appId: params.appId,
+            pid: params.pid,
+            windows: [],
+        };
+
+        const registeredApp: RegisteredApp = {
+            info: appInfo,
+            connection,
+        };
+
+        this.apps.set(params.appId, registeredApp);
+        this.connectionToApp.set(connection.id, params.appId);
+
+        const response: IpcResponse = {
+            id: request.id,
+            result: { success: true },
+        };
+        this.socketServer.send(connection.id, response);
+
+        this.emit("appRegistered", appInfo);
+    }
+
+    private handleUnregister(connection: AppConnection, request: IpcRequest): void {
+        const appId = this.connectionToApp.get(connection.id);
+        if (appId) {
+            this.apps.delete(appId);
+            this.connectionToApp.delete(connection.id);
+            this.emit("appUnregistered", appId);
+        }
+
+        const response: IpcResponse = {
+            id: request.id,
+            result: { success: true },
+        };
+        this.socketServer.send(connection.id, response);
+    }
+
+    private handleDisconnection(connection: AppConnection): void {
+        const appId = this.connectionToApp.get(connection.id);
+        if (appId) {
+            this.apps.delete(appId);
+            this.connectionToApp.delete(connection.id);
+            this.emit("appUnregistered", appId);
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+export { ConnectionManager } from "./connection-manager.js";
+export {
+    appNotFoundError,
+    invalidRequestError,
+    ipcTimeoutError,
+    McpError,
+    McpErrorCode,
+    methodNotFoundError,
+    noAppConnectedError,
+    widgetNotFoundError,
+} from "./protocol/errors.js";
+export {
+    type AppInfo,
+    DEFAULT_SOCKET_PATH,
+    getRuntimeDir,
+    type IpcError,
+    IpcErrorSchema,
+    type IpcMessage,
+    type IpcMethod,
+    type IpcRequest,
+    IpcRequestSchema,
+    type IpcResponse,
+    IpcResponseSchema,
+    type QueryOptions,
+    type SerializedWidget,
+} from "./protocol/types.js";
+export { type AppConnection, SocketServer } from "./socket-server.js";

package/src/protocol/errors.ts

@@ -0,0 +1,128 @@
+/**
+ * Error codes for MCP protocol errors.
+ */
+export enum McpErrorCode {
+    /** Internal server error */
+    INTERNAL_ERROR = 1000,
+    /** No GTKX application is connected */
+    NO_APP_CONNECTED = 1001,
+    /** Requested application ID was not found */
+    APP_NOT_FOUND = 1002,
+    /** Widget with specified ID was not found */
+    WIDGET_NOT_FOUND = 1003,
+    /** Widget cannot be interacted with */
+    WIDGET_NOT_INTERACTABLE = 1004,
+    /** Query timed out waiting for widget */
+    QUERY_TIMEOUT = 1005,
+    /** Widget is not the expected type */
+    INVALID_WIDGET_TYPE = 1006,
+    /** Screenshot capture failed */
+    SCREENSHOT_FAILED = 1007,
+    /** IPC request timed out */
+    IPC_TIMEOUT = 1008,
+    /** Failed to serialize data */
+    SERIALIZATION_ERROR = 1009,
+    /** Request format is invalid */
+    INVALID_REQUEST = 1010,
+    /** Requested method does not exist */
+    METHOD_NOT_FOUND = 1011,
+}
+
+/**
+ * Error class for MCP protocol errors.
+ *
+ * Contains an error code, message, and optional additional data.
+ */
+export class McpError extends Error {
+    /** The MCP error code */
+    readonly code: McpErrorCode;
+    /** Additional error context */
+    readonly data?: unknown;
+
+    constructor(code: McpErrorCode, message: string, data?: unknown) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = "McpError";
+
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, McpError);
+        }
+    }
+
+    /**
+     * Converts the error to an IPC-compatible format.
+     *
+     * @returns Object suitable for IPC response error field
+     */
+    toIpcError(): { code: number; message: string; data?: unknown } {
+        return {
+            code: this.code,
+            message: this.message,
+            ...(this.data !== undefined && { data: this.data }),
+        };
+    }
+}
+
+/**
+ * Creates an error for when no GTKX application is connected.
+ *
+ * @returns McpError with NO_APP_CONNECTED code
+ */
+export function noAppConnectedError(): McpError {
+    return new McpError(
+        McpErrorCode.NO_APP_CONNECTED,
+        "No GTKX application connected. Start an app with 'gtkx dev' to connect.",
+        { hint: "Run 'gtkx dev src/app.tsx' in your project directory" },
+    );
+}
+
+/**
+ * Creates an error for when a requested app is not found.
+ *
+ * @param appId - The application ID that was not found
+ * @returns McpError with APP_NOT_FOUND code
+ */
+export function appNotFoundError(appId: string): McpError {
+    return new McpError(McpErrorCode.APP_NOT_FOUND, `Application '${appId}' not found`, { appId });
+}
+
+/**
+ * Creates an error for when a widget is not found.
+ *
+ * @param widgetId - The widget ID that was not found
+ * @returns McpError with WIDGET_NOT_FOUND code
+ */
+export function widgetNotFoundError(widgetId: string): McpError {
+    return new McpError(McpErrorCode.WIDGET_NOT_FOUND, `Widget '${widgetId}' not found`, { widgetId });
+}
+
+/**
+ * Creates an error for when an IPC request times out.
+ *
+ * @param timeout - The timeout duration in milliseconds
+ * @returns McpError with IPC_TIMEOUT code
+ */
+export function ipcTimeoutError(timeout: number): McpError {
+    return new McpError(McpErrorCode.IPC_TIMEOUT, `IPC request timed out after ${timeout}ms`, { timeout });
+}
+
+/**
+ * Creates an error for invalid request format.
+ *
+ * @param reason - Description of why the request is invalid
+ * @returns McpError with INVALID_REQUEST code
+ */
+export function invalidRequestError(reason: string): McpError {
+    return new McpError(McpErrorCode.INVALID_REQUEST, `Invalid request: ${reason}`, { reason });
+}
+
+/**
+ * Creates an error for when a method is not found.
+ *
+ * @param method - The method name that was not found
+ * @returns McpError with METHOD_NOT_FOUND code
+ */
+export function methodNotFoundError(method: string): McpError {
+    return new McpError(McpErrorCode.METHOD_NOT_FOUND, `Method '${method}' not found`, { method });
+}

package/src/protocol/types.ts

@@ -0,0 +1,153 @@
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+
+/**
+ * Zod schema for validating IPC requests.
+ */
+export const IpcRequestSchema = z.object({
+    id: z.string(),
+    method: z.string(),
+    params: z.unknown().optional(),
+});
+
+/**
+ * An IPC request message.
+ */
+export type IpcRequest = z.infer<typeof IpcRequestSchema>;
+
+/**
+ * An IPC error object.
+ */
+export type IpcError = {
+    /** Error code */
+    code: number;
+    /** Error message */
+    message: string;
+    /** Additional error data */
+    data?: unknown;
+};
+
+/**
+ * Zod schema for validating IPC errors.
+ */
+export const IpcErrorSchema = z.object({
+    code: z.number(),
+    message: z.string(),
+    data: z.unknown().optional(),
+});
+
+/**
+ * Zod schema for validating IPC responses.
+ */
+export const IpcResponseSchema = z.object({
+    id: z.string(),
+    result: z.unknown().optional(),
+    error: IpcErrorSchema.optional(),
+});
+
+/**
+ * An IPC response message.
+ */
+export type IpcResponse = z.infer<typeof IpcResponseSchema>;
+
+/**
+ * A serialized representation of a GTK widget for IPC transfer.
+ */
+export type SerializedWidget = {
+    /** Unique widget identifier */
+    id: string;
+    /** Widget type name (e.g., "GtkButton") */
+    type: string;
+    /** Accessible role */
+    role: string;
+    /** Widget name (test ID) */
+    name: string | null;
+    /** Accessible label */
+    label: string | null;
+    /** Text content */
+    text: string | null;
+    /** Whether the widget is sensitive (interactive) */
+    sensitive: boolean;
+    /** Whether the widget is visible */
+    visible: boolean;
+    /** CSS class names */
+    cssClasses: string[];
+    /** Child widgets */
+    children: SerializedWidget[];
+    /** Widget bounds in window coordinates */
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+};
+
+/**
+ * Information about a connected GTKX application.
+ */
+export type AppInfo = {
+    /** Application ID (e.g., "com.example.myapp") */
+    appId: string;
+    /** Process ID */
+    pid: number;
+    /** Open windows */
+    windows: Array<{
+        id: string;
+        title: string | null;
+    }>;
+};
+
+/**
+ * Options for widget queries.
+ */
+export type QueryOptions = {
+    /** Widget name to match */
+    name?: string;
+    /** Require exact match */
+    exact?: boolean;
+    /** Query timeout in milliseconds */
+    timeout?: number;
+};
+
+/**
+ * Zod schema for app registration parameters.
+ * @internal
+ */
+export const RegisterParamsSchema = z.object({
+    appId: z.string(),
+    pid: z.number(),
+});
+
+/**
+ * Available IPC methods.
+ */
+export type IpcMethod =
+    | "app.register"
+    | "app.unregister"
+    | "app.getWindows"
+    | "widget.getTree"
+    | "widget.query"
+    | "widget.getProps"
+    | "widget.click"
+    | "widget.type"
+    | "widget.fireEvent"
+    | "widget.screenshot";
+
+/**
+ * Union type for any IPC message (request or response).
+ */
+export type IpcMessage = IpcRequest | IpcResponse;
+
+/**
+ * Gets the XDG runtime directory or falls back to system temp.
+ *
+ * @returns Path to the runtime directory
+ */
+export const getRuntimeDir = (): string => process.env.XDG_RUNTIME_DIR ?? tmpdir();
+
+/**
+ * Default path for the MCP socket file.
+ */
+export const DEFAULT_SOCKET_PATH = join(getRuntimeDir(), "gtkx-mcp.sock");