@gtkx/mcp 0.20.0 → 1.0.0-rc.1

package/src/connection-manager.ts

@@ -1,247 +0,0 @@
-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

@@ -1,27 +0,0 @@
-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/types.ts

@@ -1,153 +0,0 @@
-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");