@gtkx/mcp 0.21.0 → 1.0.0-rc.1

package/src/cli.ts

@@ -1,449 +0,0 @@
-#!/usr/bin/env node
-
-import { createRequire } from "node:module";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { z } from "zod";
-import { ConnectionManager } from "./connection-manager.js";
-import { DEFAULT_SOCKET_PATH } from "./protocol/types.js";
-import { SocketServer } from "./socket-server.js";
-
-const require = createRequire(import.meta.url);
-const { version } = require("../package.json") as { version: string };
-
-const AppIdSchema = z.object({
-    appId: z.string().optional().describe("App ID to query. If not specified, uses the first connected app."),
-});
-
-const ListAppsInputSchema = z.object({
-    waitForApps: z
-        .boolean()
-        .optional()
-        .describe(
-            "If true, wait for at least one app to register before returning. Useful when app is still starting.",
-        ),
-    timeout: z.number().optional().describe("Timeout in milliseconds when waitForApps is true (default: 10000)"),
-});
-
-const GetWidgetTreeInputSchema = AppIdSchema;
-
-const QueryWidgetsInputSchema = AppIdSchema.extend({
-    by: z.enum(["role", "text", "name", "labelText"]).describe("Query type"),
-    value: z.union([z.string(), z.number()]).describe("Value to search for"),
-    options: z
-        .object({
-            name: z.string().optional(),
-            exact: z.boolean().optional(),
-            timeout: z.number().optional(),
-        })
-        .optional()
-        .describe("Additional query options"),
-});
-
-const WidgetIdSchema = AppIdSchema.extend({
-    widgetId: z.string().describe("Widget ID"),
-});
-
-const GetWidgetPropsInputSchema = WidgetIdSchema;
-
-const ClickInputSchema = WidgetIdSchema;
-
-const TypeInputSchema = WidgetIdSchema.extend({
-    text: z.string().describe("Text to type"),
-    clear: z.boolean().optional().describe("Clear existing text before typing"),
-});
-
-const FireEventInputSchema = WidgetIdSchema.extend({
-    signal: z.string().describe("GTK signal name to emit"),
-    args: z.array(z.unknown()).optional().describe("Arguments to pass to the signal"),
-});
-
-const TakeScreenshotInputSchema = AppIdSchema.extend({
-    windowId: z.string().optional().describe("Window ID to capture. If not specified, captures the first window."),
-});
-
-const tools = [
-    {
-        name: "gtkx_list_apps",
-        description: "List all connected GTKX applications",
-        inputSchema: {
-            type: "object" as const,
-            properties: {
-                waitForApps: {
-                    type: "boolean",
-                    description:
-                        "If true, wait for at least one app to register before returning. Useful when app is still starting.",
-                },
-                timeout: {
-                    type: "number",
-                    description: "Timeout in milliseconds when waitForApps is true (default: 10000)",
-                },
-            },
-            required: [],
-        },
-    },
-    {
-        name: "gtkx_get_widget_tree",
-        description:
-            "Get the widget hierarchy for a connected GTKX app. Returns a tree of all widgets with their IDs, types, roles, and properties.",
-        inputSchema: {
-            type: "object" as const,
-            properties: {
-                appId: {
-                    type: "string",
-                    description: "App ID to query. If not specified, uses the first connected app.",
-                },
-            },
-            required: [],
-        },
-    },
-    {
-        name: "gtkx_query_widgets",
-        description:
-            "Find widgets by role, text, name, or label. Returns matching widgets with their IDs and properties.",
-        inputSchema: {
-            type: "object" as const,
-            properties: {
-                appId: {
-                    type: "string",
-                    description: "App ID to query. If not specified, uses the first connected app.",
-                },
-                by: {
-                    type: "string",
-                    enum: ["role", "text", "name", "labelText"],
-                    description: "Query type",
-                },
-                value: {
-                    oneOf: [{ type: "string" }, { type: "number" }],
-                    description: "Value to search for",
-                },
-                options: {
-                    type: "object",
-                    properties: {
-                        name: { type: "string" },
-                        exact: { type: "boolean" },
-                        timeout: { type: "number" },
-                    },
-                    description: "Additional query options",
-                },
-            },
-            required: ["by", "value"],
-        },
-    },
-    {
-        name: "gtkx_get_widget_props",
-        description: "Get all properties of a specific widget by its ID",
-        inputSchema: {
-            type: "object" as const,
-            properties: {
-                appId: {
-                    type: "string",
-                    description: "App ID to query. If not specified, uses the first connected app.",
-                },
-                widgetId: {
-                    type: "string",
-                    description: "Widget ID to get properties for",
-                },
-            },
-            required: ["widgetId"],
-        },
-    },
-    {
-        name: "gtkx_click",
-        description: "Click a widget. Works with buttons, checkboxes, and other interactive widgets.",
-        inputSchema: {
-            type: "object" as const,
-            properties: {
-                appId: {
-                    type: "string",
-                    description: "App ID to query. If not specified, uses the first connected app.",
-                },
-                widgetId: {
-                    type: "string",
-                    description: "Widget ID to click",
-                },
-            },
-            required: ["widgetId"],
-        },
-    },
-    {
-        name: "gtkx_type",
-        description: "Type text into an editable widget like Entry or TextView",
-        inputSchema: {
-            type: "object" as const,
-            properties: {
-                appId: {
-                    type: "string",
-                    description: "App ID to query. If not specified, uses the first connected app.",
-                },
-                widgetId: {
-                    type: "string",
-                    description: "Widget ID to type into",
-                },
-                text: {
-                    type: "string",
-                    description: "Text to type",
-                },
-                clear: {
-                    type: "boolean",
-                    description: "Clear existing text before typing",
-                },
-            },
-            required: ["widgetId", "text"],
-        },
-    },
-    {
-        name: "gtkx_fire_event",
-        description: "Emit a GTK signal on a widget. Use this for custom interactions.",
-        inputSchema: {
-            type: "object" as const,
-            properties: {
-                appId: {
-                    type: "string",
-                    description: "App ID to query. If not specified, uses the first connected app.",
-                },
-                widgetId: {
-                    type: "string",
-                    description: "Widget ID to emit event on",
-                },
-                signal: {
-                    type: "string",
-                    description: "GTK signal name to emit",
-                },
-                args: {
-                    type: "array",
-                    items: {},
-                    description: "Arguments to pass to the signal",
-                },
-            },
-            required: ["widgetId", "signal"],
-        },
-    },
-    {
-        name: "gtkx_take_screenshot",
-        description: "Capture a screenshot of a window. Returns base64-encoded PNG image data.",
-        inputSchema: {
-            type: "object" as const,
-            properties: {
-                appId: {
-                    type: "string",
-                    description: "App ID to query. If not specified, uses the first connected app.",
-                },
-                windowId: {
-                    type: "string",
-                    description: "Window ID to capture. If not specified, captures the first window.",
-                },
-            },
-            required: [],
-        },
-    },
-];
-
-async function main() {
-    const socketServer = new SocketServer(DEFAULT_SOCKET_PATH);
-    const connectionManager = new ConnectionManager(socketServer);
-
-    socketServer.on("error", (error) => {
-        const code = (error as NodeJS.ErrnoException).code;
-        if (code !== "EPIPE" && code !== "ECONNRESET") {
-            console.error("[gtkx] Socket error:", error.message);
-        }
-    });
-
-    await socketServer.start();
-    console.error(`[gtkx] Socket server listening on ${DEFAULT_SOCKET_PATH}`);
-
-    connectionManager.on("appRegistered", (appInfo) => {
-        console.error(`[gtkx] App registered: ${appInfo.appId} (PID: ${appInfo.pid})`);
-    });
-
-    connectionManager.on("appUnregistered", (appId) => {
-        console.error(`[gtkx] App unregistered: ${appId}`);
-    });
-
-    const server = new Server(
-        {
-            name: "gtkx-mcp",
-            version,
-        },
-        {
-            capabilities: {
-                tools: {},
-            },
-        },
-    );
-
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
-        return { tools };
-    });
-
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const { name, arguments: args } = request.params;
-
-        try {
-            switch (name) {
-                case "gtkx_list_apps": {
-                    const input = ListAppsInputSchema.parse(args);
-
-                    if (input.waitForApps && !connectionManager.hasConnectedApps()) {
-                        try {
-                            await connectionManager.waitForApp(input.timeout);
-                        } catch (error) {
-                            return {
-                                content: [
-                                    {
-                                        type: "text",
-                                        text: error instanceof Error ? error.message : "Timeout waiting for app",
-                                    },
-                                ],
-                                isError: true,
-                            };
-                        }
-                    }
-
-                    const apps = connectionManager.getApps();
-                    const appsWithWindows = await Promise.all(
-                        apps.map(async (app) => {
-                            try {
-                                const result = await connectionManager.sendToApp<{
-                                    windows: Array<{ id: string; title: string | null }>;
-                                }>(app.appId, "app.getWindows", {});
-                                return { ...app, windows: result.windows };
-                            } catch {
-                                return app;
-                            }
-                        }),
-                    );
-                    return {
-                        content: [{ type: "text", text: JSON.stringify(appsWithWindows, null, 2) }],
-                    };
-                }
-
-                case "gtkx_get_widget_tree": {
-                    const input = GetWidgetTreeInputSchema.parse(args);
-                    const result = await connectionManager.sendToApp<{ tree: string }>(
-                        input.appId,
-                        "widget.getTree",
-                        {},
-                    );
-                    return {
-                        content: [{ type: "text", text: result.tree }],
-                    };
-                }
-
-                case "gtkx_query_widgets": {
-                    const input = QueryWidgetsInputSchema.parse(args);
-                    const result = await connectionManager.sendToApp(input.appId, "widget.query", {
-                        queryType: input.by,
-                        value: input.value,
-                        options: input.options,
-                    });
-                    return {
-                        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-                    };
-                }
-
-                case "gtkx_get_widget_props": {
-                    const input = GetWidgetPropsInputSchema.parse(args);
-                    const result = await connectionManager.sendToApp(input.appId, "widget.getProps", {
-                        widgetId: input.widgetId,
-                    });
-                    return {
-                        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-                    };
-                }
-
-                case "gtkx_click": {
-                    const input = ClickInputSchema.parse(args);
-                    await connectionManager.sendToApp(input.appId, "widget.click", {
-                        widgetId: input.widgetId,
-                    });
-                    return {
-                        content: [{ type: "text", text: "Click successful" }],
-                    };
-                }
-
-                case "gtkx_type": {
-                    const input = TypeInputSchema.parse(args);
-                    await connectionManager.sendToApp(input.appId, "widget.type", {
-                        widgetId: input.widgetId,
-                        text: input.text,
-                        clear: input.clear,
-                    });
-                    return {
-                        content: [{ type: "text", text: "Type successful" }],
-                    };
-                }
-
-                case "gtkx_fire_event": {
-                    const input = FireEventInputSchema.parse(args);
-                    await connectionManager.sendToApp(input.appId, "widget.fireEvent", {
-                        widgetId: input.widgetId,
-                        signal: input.signal,
-                        args: input.args,
-                    });
-                    return {
-                        content: [{ type: "text", text: "Event fired successfully" }],
-                    };
-                }
-
-                case "gtkx_take_screenshot": {
-                    const input = TakeScreenshotInputSchema.parse(args);
-                    const result = await connectionManager.sendToApp<{ data: string; mimeType: string }>(
-                        input.appId,
-                        "widget.screenshot",
-                        {
-                            windowId: input.windowId,
-                        },
-                    );
-                    return {
-                        content: [
-                            {
-                                type: "image",
-                                data: result.data,
-                                mimeType: result.mimeType,
-                            },
-                        ],
-                    };
-                }
-
-                default:
-                    return {
-                        content: [{ type: "text", text: `Unknown tool: ${name}` }],
-                        isError: true,
-                    };
-            }
-        } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return {
-                content: [{ type: "text", text: message }],
-                isError: true,
-            };
-        }
-    });
-
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-
-    let isShuttingDown = false;
-    const shutdown = async () => {
-        if (isShuttingDown) return;
-        isShuttingDown = true;
-        try {
-            connectionManager.cleanup();
-            await socketServer.stop();
-            await server.close();
-        } finally {
-            process.exit(0);
-        }
-    };
-
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
-}
-
-main().catch((error) => {
-    console.error("[gtkx] Fatal error:", error);
-    process.exit(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);
-        }
-    }
-}