@gtkx/mcp 0.21.0 → 1.0.0-rc.1

package/src/server.ts

@@ -0,0 +1,281 @@
+import { createRequire } from "node:module";
+import { createLogger, installGracefulShutdown, type Logger } from "@gtkx/utils";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { AppRouter } from "./app-router.js";
+import { ConnectionRegistry } from "./connection-registry.js";
+import {
+    DEFAULT_SOCKET_PATH,
+    fireEventParams,
+    queryParams,
+    screenshotParams,
+    typeParams,
+    widgetIdParams,
+} from "./protocol/schemas.js";
+import { buildReferenceTools, createReferenceProvider, registerReferenceResources } from "./reference.js";
+import { SocketServer } from "./socket-server.js";
+import { defineTool, imageContent, registerTool, type Tool, textContent } from "./tool.js";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json") as { version: string };
+
+export const log: Logger = createLogger("mcp");
+
+const APPLICATION_ID_DESCRIPTION = "Application ID to query. If not specified, uses the first connected app.";
+const WIDGET_ID_DESCRIPTION =
+    "Widget ID obtained from `gtkx_get_widget_tree`, `gtkx_query_widgets`, or `gtkx_get_widget_props`. IDs are scoped to a single app. An ID stays valid for as long as its widget is mounted and stops resolving once the widget is unmounted.";
+
+const applicationIdShape = { applicationId: z.string().optional().describe(APPLICATION_ID_DESCRIPTION) };
+const widgetIdShape = {
+    ...applicationIdShape,
+    widgetId: widgetIdParams.shape.widgetId.describe(WIDGET_ID_DESCRIPTION),
+};
+
+const listAppsShape = {
+    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 queryWidgetsShape = {
+    ...applicationIdShape,
+    by: queryParams.shape.by.describe("Query type"),
+    value: queryParams.shape.value.describe("Value to search for"),
+    options: queryParams.shape.options.describe("Additional query options"),
+};
+
+const typeShape = {
+    ...widgetIdShape,
+    text: typeParams.shape.text.describe("Text to type"),
+    clear: typeParams.shape.clear.describe("Clear existing text before typing"),
+};
+
+const fireEventShape = {
+    ...widgetIdShape,
+    signal: fireEventParams.shape.signal.describe("GTK4 signal name to emit"),
+    args: fireEventParams.shape.args.describe("Arguments to pass to the signal"),
+};
+
+const screenshotShape = {
+    ...applicationIdShape,
+    windowId: screenshotParams.shape.windowId.describe(
+        "Window ID to capture. If not specified, captures the first window.",
+    ),
+    path: screenshotParams.shape.path.describe(
+        "Absolute path to write the PNG to on the app's machine. If set, the screenshot is saved there in addition to being returned.",
+    ),
+};
+
+const listAppsTool = (appRouter: AppRouter): Tool =>
+    defineTool({
+        name: "gtkx_list_apps",
+        title: "List apps",
+        kind: "readOnly",
+        description: "List all connected GTKX applications and their open windows.",
+        inputSchema: listAppsShape,
+        handler: async ({ waitForApps, timeout }) => {
+            if (waitForApps && !appRouter.hasConnectedApps()) {
+                await appRouter.waitForApp(timeout);
+            }
+
+            const apps = appRouter.getApps();
+            const appsWithWindows = await Promise.all(
+                apps.map(async (app) => {
+                    try {
+                        const result = await appRouter.sendToApp<{
+                            windows: Array<{ id: string; title: string | null }>;
+                        }>(app.applicationId, "app.getWindows", {});
+                        return { ...app, windows: result.windows };
+                    } catch {
+                        return app;
+                    }
+                }),
+            );
+            return textContent(JSON.stringify(appsWithWindows, null, 2));
+        },
+    });
+
+const screenshotTool = (appRouter: AppRouter): Tool =>
+    defineTool({
+        name: "gtkx_take_screenshot",
+        title: "Take screenshot",
+        kind: "readOnly",
+        description:
+            "Capture a screenshot of a window. Returns base64-encoded PNG image data, and optionally writes the PNG to `path` on the app's machine. You can't target widgets from a screenshot; use `gtkx_get_widget_tree` to find widget IDs for interaction.",
+        inputSchema: screenshotShape,
+        handler: async ({ applicationId, ...params }) => {
+            const result = await appRouter.sendToApp<{ data: string; mimeType: string; savedPath?: string }>(
+                applicationId,
+                "widget.screenshot",
+                params,
+            );
+            if (result.savedPath) {
+                return {
+                    content: [
+                        { type: "text", text: `Screenshot saved to ${result.savedPath}` },
+                        { type: "image", data: result.data, mimeType: result.mimeType },
+                    ],
+                };
+            }
+            return imageContent(result.data, result.mimeType);
+        },
+    });
+
+function buildInspectionTools(appRouter: AppRouter): Tool[] {
+    return [
+        listAppsTool(appRouter),
+        defineTool({
+            name: "gtkx_get_widget_tree",
+            title: "Widget tree",
+            kind: "readOnly",
+            description:
+                "Get the widget hierarchy for a connected GTKX app. Returns a tree of all widgets with their IDs, types, roles, and properties.",
+            inputSchema: applicationIdShape,
+            handler: async ({ applicationId }) => {
+                const result = await appRouter.sendToApp<{ tree: string }>(applicationId, "widget.getTree", {});
+                return textContent(result.tree);
+            },
+        }),
+        defineTool({
+            name: "gtkx_query_widgets",
+            title: "Query widgets",
+            kind: "readOnly",
+            description:
+                "Find widgets by role, text, name, or label. Returns matching widgets with their IDs and properties.",
+            inputSchema: queryWidgetsShape,
+            handler: async ({ applicationId, ...params }) => {
+                const result = await appRouter.sendToApp(applicationId, "widget.query", params);
+                return textContent(JSON.stringify(result, null, 2));
+            },
+        }),
+        defineTool({
+            name: "gtkx_get_widget_props",
+            title: "Get widget properties",
+            kind: "readOnly",
+            description:
+                "Get a fixed summary of one widget by ID: type, accessible role, name, text, sensitivity, visibility, CSS classes, and the full subtree of descendant widgets. It does not return arbitrary GObject properties.",
+            inputSchema: widgetIdShape,
+            handler: async ({ applicationId, ...params }) => {
+                const result = await appRouter.sendToApp(applicationId, "widget.getProps", params);
+                return textContent(JSON.stringify(result, null, 2));
+            },
+        }),
+        screenshotTool(appRouter),
+    ];
+}
+
+function buildInteractionTools(appRouter: AppRouter): Tool[] {
+    return [
+        defineTool({
+            name: "gtkx_click",
+            title: "Click widget",
+            kind: "action",
+            description: "Click a widget. Works with buttons, checkboxes, and other interactive widgets.",
+            inputSchema: widgetIdShape,
+            handler: async ({ applicationId, ...params }) => {
+                await appRouter.sendToApp(applicationId, "widget.click", params);
+                return textContent("Clicked");
+            },
+        }),
+        defineTool({
+            name: "gtkx_type",
+            title: "Type text",
+            kind: "action",
+            description: "Type text into an editable widget like Entry or TextView",
+            inputSchema: typeShape,
+            handler: async ({ applicationId, ...params }) => {
+                await appRouter.sendToApp(applicationId, "widget.type", params);
+                return textContent("Typed text");
+            },
+        }),
+        defineTool({
+            name: "gtkx_fire_event",
+            title: "Fire event",
+            kind: "action",
+            description: "Emit a GTK4 signal on a widget. Use this for custom interactions.",
+            inputSchema: fireEventShape,
+            handler: async ({ applicationId, ...params }) => {
+                await appRouter.sendToApp(applicationId, "widget.fireEvent", params);
+                return textContent("Fired event");
+            },
+        }),
+    ];
+}
+
+function buildTools(appRouter: AppRouter): Tool[] {
+    return [...buildInspectionTools(appRouter), ...buildInteractionTools(appRouter)];
+}
+
+type CreateMcpServerOptions = {
+    socketPath?: string;
+    version: string;
+};
+
+type McpServerHandle = {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+};
+
+export const createMcpServer = (options: CreateMcpServerOptions): McpServerHandle => {
+    const socketPath = options.socketPath ?? DEFAULT_SOCKET_PATH;
+
+    const registry = new ConnectionRegistry();
+    const socketServer = new SocketServer(registry, socketPath);
+    const appRouter = new AppRouter(registry);
+
+    registry.on("error", (error) => {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== "EPIPE" && code !== "ECONNRESET") {
+            log.error(`socket error: ${error.message}`);
+        }
+    });
+
+    appRouter.on("appRegistered", (appInfo) => {
+        log.info(`app registered: ${appInfo.applicationId} (PID: ${appInfo.pid})`);
+    });
+
+    appRouter.on("appUnregistered", (applicationId) => {
+        log.info(`app unregistered: ${applicationId}`);
+    });
+
+    const mcpServer = new McpServer({ name: "gtkx-mcp", version: options.version });
+
+    const referenceProvider = createReferenceProvider(() => appRouter.getProjectRoot() ?? process.cwd());
+
+    for (const tool of [...buildTools(appRouter), ...buildReferenceTools(referenceProvider)]) {
+        registerTool(mcpServer, tool);
+    }
+    registerReferenceResources(mcpServer, referenceProvider);
+
+    let stopped = false;
+
+    return {
+        async start() {
+            await socketServer.start();
+            log.info(`socket server listening on ${socketPath}`);
+            const transport = new StdioServerTransport();
+            process.stdin.on("end", () => void this.stop());
+            process.stdin.on("close", () => void this.stop());
+            await mcpServer.connect(transport);
+        },
+        async stop() {
+            if (stopped) return;
+            stopped = true;
+            await socketServer.stop();
+            await mcpServer.close();
+        },
+    };
+};
+
+export async function main(): Promise<void> {
+    const server = createMcpServer({ version });
+    installGracefulShutdown({
+        onSignal: () => server.stop(),
+    });
+    await server.start();
+}

package/src/socket-server.ts

@@ -1,99 +1,61 @@
-import EventEmitter from "node:events";
 import * as fs from "node:fs";
 import * as net from "node:net";
-import { invalidRequestError } from "./protocol/errors.js";
-import {
-    DEFAULT_SOCKET_PATH,
-    type IpcMessage,
-    type IpcRequest,
-    IpcRequestSchema,
-    type IpcResponse,
-    IpcResponseSchema,
-} from "./protocol/types.js";
-
-type SocketServerEventMap = {
-    connection: [AppConnection];
-    disconnection: [AppConnection];
-    request: [AppConnection, IpcRequest];
-    response: [AppConnection, IpcResponse];
-    error: [Error];
-};
-
-/**
- * Represents a connected application.
- */
-export type AppConnection = {
-    /** Unique connection identifier */
-    id: string;
-    /** The underlying socket */
-    socket: net.Socket;
-    /** Buffer for incomplete messages */
-    buffer: string;
-};
+import type { ConnectionRegistry } from "./connection-registry.js";
+import { DEFAULT_SOCKET_PATH } from "./protocol/schemas.js";
+
+const isSocketLive = (socketPath: string): Promise<boolean> =>
+    new Promise((resolve) => {
+        const probe = net.connect(socketPath);
+        probe.once("connect", () => {
+            probe.destroy();
+            resolve(true);
+        });
+        probe.once("error", () => resolve(false));
+    });
 
-/**
- * Unix domain socket server for MCP communication.
- *
- * Manages connections from GTKX applications and handles IPC messaging.
- */
-export class SocketServer extends EventEmitter<SocketServerEventMap> {
+export class SocketServer {
     private server: net.Server | null = null;
-    private connections: Map<string, AppConnection> = new Map();
     private socketPath: string;
+    private registry: ConnectionRegistry;
 
-    constructor(socketPath: string = DEFAULT_SOCKET_PATH) {
-        super();
+    constructor(registry: ConnectionRegistry, socketPath: string = DEFAULT_SOCKET_PATH) {
+        this.registry = registry;
         this.socketPath = socketPath;
     }
 
-    get path(): string {
-        return this.socketPath;
-    }
-
-    get isListening(): boolean {
-        return this.server?.listening ?? false;
-    }
-
-    getConnections(): AppConnection[] {
-        return Array.from(this.connections.values());
-    }
-
-    getConnection(id: string): AppConnection | undefined {
-        return this.connections.get(id);
-    }
-
     async start(): Promise<void> {
-        if (this.server) {
-            return;
-        }
+        if (this.server) return;
 
         if (fs.existsSync(this.socketPath)) {
+            if (await isSocketLive(this.socketPath)) {
+                throw new Error(
+                    `Another GTKX MCP server already owns ${this.socketPath}. ` +
+                        "Stop the other server (for example, the gtkx MCP server of another active session) and reconnect.",
+                );
+            }
             fs.unlinkSync(this.socketPath);
         }
 
         return new Promise((resolve, reject) => {
-            this.server = net.createServer((socket) => this.handleConnection(socket));
+            this.server = net.createServer((socket) => this.registry.register(socket));
 
+            let listening = false;
             this.server.on("error", (error) => {
-                this.emit("error", error);
-                reject(error);
+                this.registry.emit("error", error);
+                if (!listening) reject(error);
             });
 
             this.server.listen(this.socketPath, () => {
+                listening = true;
                 resolve();
             });
         });
     }
 
     async stop(): Promise<void> {
-        if (!this.server) {
-            return;
-        }
+        if (!this.server) return;
 
-        for (const connection of this.connections.values()) {
-            connection.socket.destroy();
-        }
-        this.connections.clear();
+        this.registry.dispose("Server stopping");
 
         return new Promise((resolve) => {
             this.server?.close(() => {
@@ -105,90 +67,4 @@ export class SocketServer extends EventEmitter<SocketServerEventMap> {
             });
         });
     }
-
-    send(connectionId: string, message: IpcMessage): boolean {
-        const connection = this.connections.get(connectionId);
-        if (!connection?.socket.writable) {
-            return false;
-        }
-
-        const data = `${JSON.stringify(message)}\n`;
-        connection.socket.write(data);
-        return true;
-    }
-
-    private handleConnection(socket: net.Socket): void {
-        const connectionId = crypto.randomUUID();
-        const connection: AppConnection = {
-            id: connectionId,
-            socket,
-            buffer: "",
-        };
-
-        this.connections.set(connectionId, connection);
-        this.emit("connection", connection);
-
-        socket.on("data", (data: Buffer) => this.handleData(connection, data));
-
-        socket.on("close", () => {
-            this.connections.delete(connectionId);
-            this.emit("disconnection", connection);
-        });
-
-        socket.on("error", (error) => {
-            this.emit("error", error);
-        });
-    }
-
-    private handleData(connection: AppConnection, data: Buffer): void {
-        connection.buffer += data.toString();
-
-        let newlineIndex = connection.buffer.indexOf("\n");
-        while (newlineIndex !== -1) {
-            const line = connection.buffer.slice(0, newlineIndex);
-            connection.buffer = connection.buffer.slice(newlineIndex + 1);
-
-            if (line.trim()) {
-                this.processMessage(connection, line);
-            }
-            newlineIndex = connection.buffer.indexOf("\n");
-        }
-    }
-
-    private processMessage(connection: AppConnection, line: string): void {
-        let parsed: unknown;
-        try {
-            parsed = JSON.parse(line);
-        } catch {
-            const response: IpcResponse = {
-                id: "unknown",
-                error: invalidRequestError("Invalid JSON").toIpcError(),
-            };
-            this.send(connection.id, response);
-            return;
-        }
-
-        const message = parsed as Record<string, unknown>;
-        const hasMethod = typeof message.method === "string";
-
-        if (hasMethod) {
-            const requestResult = IpcRequestSchema.safeParse(parsed);
-            if (requestResult.success) {
-                this.emit("request", connection, requestResult.data);
-                return;
-            }
-        } else {
-            const responseResult = IpcResponseSchema.safeParse(parsed);
-            if (responseResult.success) {
-                this.emit("response", connection, responseResult.data);
-                return;
-            }
-        }
-
-        const response: IpcResponse = {
-            id: (message.id as string | undefined) ?? "unknown",
-            error: invalidRequestError("Invalid message format").toIpcError(),
-        };
-        this.send(connection.id, response);
-    }
 }

package/src/tool.ts

@@ -0,0 +1,66 @@
+import type { McpServer, ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { z } from "zod";
+import { ProtocolError } from "./protocol/errors.js";
+
+export const textContent = (text: string): CallToolResult => ({ content: [{ type: "text", text }] });
+
+export const textError = (text: string): CallToolResult => ({
+    content: [{ type: "text", text }],
+    isError: true,
+});
+
+export const imageContent = (data: string, mimeType: string): CallToolResult => ({
+    content: [{ type: "image", data, mimeType }],
+});
+
+export type ToolArgs<Shape extends Record<string, z.ZodType>> = { [K in keyof Shape]: z.output<Shape[K]> };
+
+type ToolKind = "readOnly" | "action";
+
+export type Tool<Shape extends Record<string, z.ZodType> = Record<string, z.ZodType>> = {
+    name: string;
+    title: string;
+    kind: ToolKind;
+    description: string;
+    inputSchema: Shape;
+    handler: (args: ToolArgs<Shape>) => Promise<CallToolResult>;
+};
+
+const hasStringHint = (data: unknown): data is { hint: string } =>
+    typeof data === "object" && data !== null && "hint" in data && typeof data.hint === "string";
+
+const runTool = async (
+    handler: (args: ToolArgs<Record<string, z.ZodType>>) => Promise<CallToolResult>,
+    args: ToolArgs<Record<string, z.ZodType>>,
+): Promise<CallToolResult> => {
+    try {
+        return await handler(args);
+    } catch (error) {
+        if (error instanceof ProtocolError) {
+            return textError(hasStringHint(error.data) ? `${error.message}\n${error.data.hint}` : error.message);
+        }
+        return textError(error instanceof Error ? error.message : String(error));
+    }
+};
+
+export const defineTool = <Shape extends Record<string, z.ZodType>>(tool: Tool<Shape>): Tool => tool as Tool;
+
+export const registerTool = (server: McpServer, tool: Tool): void => {
+    const callback = ((args: ToolArgs<Record<string, z.ZodType>>, _extra: unknown) =>
+        runTool(tool.handler, args)) as ToolCallback<Record<string, z.ZodType>>;
+    server.registerTool(
+        tool.name,
+        {
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: {
+                title: tool.title,
+                readOnlyHint: tool.kind === "readOnly",
+                destructiveHint: tool.kind === "action",
+                openWorldHint: true,
+            },
+        },
+        callback,
+    );
+};