@gtkx/mcp 1.0.0-rc.4 → 1.1.0

package/src/server.ts

@@ -1,22 +1,30 @@
 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 { createRequire } from "node:module";
 import { z } from "zod";
 import type { ConnectionErrorEvent } from "./transport.js";
+import packageManifest from "../package.json" with { type: "json" };
 import { type AppRegisteredEvent, AppRouter, type AppUnregisteredEvent } from "./app-router.js";
 import { ConnectionRegistry } from "./connection-registry.js";
 import {
     type AppInfo,
     DEFAULT_SOCKET_PATH,
+    DEFAULT_SUBTREE_DEPTH,
     fireEventParams,
+    MAX_SUBTREE_WIDGETS,
     queryParams,
     screenshotParams,
     treeParams,
     typeParams,
     widgetIdParams,
+    widgetPropsParams,
 } from "./protocol/schemas.js";
-import { buildReferenceTools, createReferenceProvider, registerReferenceResources } from "./reference.js";
+import {
+    buildReferenceTools,
+    createReferenceProvider,
+    type ReferenceProvider,
+    registerReferenceResources,
+} from "./reference.js";
 import { SocketServer } from "./socket-server.js";
 import { defineTool, imageContent, registerTool, textContent, type Tool } from "./tool.js";
 
@@ -30,11 +38,18 @@ type McpServerHandle = {
     stop(): Promise<void>;
 };
 
+type ServerLifecycle = {
+    socketServer: SocketServer;
+    mcpServer: McpServer;
+    socketPath: string;
+    isStopped: boolean;
+    isStarted: boolean;
+};
+
 type AppWindow = { id: string; title: string | null };
 type AppWithWindows = AppInfo & { windows?: AppWindow[] };
 
-const require = createRequire(import.meta.url);
-const { version } = require("../package.json") as { version: string };
+const { version } = packageManifest;
 const log: Logger = createLogger("mcp");
 const APPLICATION_ID_DESCRIPTION = "Application ID to query. If not specified, uses the first connected app.";
 
@@ -47,18 +62,34 @@ const applicationIdShape = { applicationId: z.string().optional().describe(APPLI
 
 const widgetIdShape = {
     ...applicationIdShape,
-    widgetId: widgetIdParams.shape.widgetId.describe(WIDGET_ID_DESCRIPTION),
+    ...describeParams(widgetIdParams.shape, { widgetId: WIDGET_ID_DESCRIPTION }),
+};
+
+const widgetPropsShape = {
+    ...applicationIdShape,
+    ...describeParams(widgetPropsParams.shape, {
+        widgetId: WIDGET_ID_DESCRIPTION,
+        properties:
+            "GObject property names to read as well, in kebab-case or camelCase (\"current-breakpoint\" or " +
+            "\"currentBreakpoint\"). Omit for the summary alone.",
+        maxDepth:
+            `How many levels of descendants to include: ${String(DEFAULT_SUBTREE_DEPTH)} by default, and 0 ` +
+            `for the widget on its own. At most ${String(MAX_SUBTREE_WIDGETS)} widgets come back whatever ` +
+            "the depth, and any widget whose own direct children were left out carries a `hiddenChildren` count.",
+    }),
 };
 
 const treeShape = {
     ...applicationIdShape,
-    rootId: treeParams.shape.rootId.describe(
-        "Render only the subtree rooted at this widget ID (from a prior tree or query). Omit for the whole app.",
-    ),
-    maxDepth: treeParams.shape.maxDepth.describe(
-        "Limit how many levels deep to render; deeper descendants are summarized with a count. " +
-        "Combine with rootId to drill in without dumping the whole tree.",
-    ),
+    ...describeParams(treeParams.shape, {
+        rootId:
+            "Render only the subtree rooted at this widget ID (from a prior tree or query). Omit for the " +
+            "whole app.",
+        maxDepth:
+            "Limit how many levels deep to render, and 0 for the root widget on its own; deeper " +
+            "descendants are summarized with a count. Combine with rootId to drill in without dumping " +
+            "the whole tree.",
+    }),
 };
 
 const listAppsShape = {
@@ -73,32 +104,58 @@ const listAppsShape = {
 
 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"),
+    ...describeParams(queryParams.shape, {
+        by: "Query type",
+        value: "Value to search for",
+        options: "Additional query options",
+    }),
 };
 
 const typeShape = {
-    ...widgetIdShape,
-    text: typeParams.shape.text.describe("Text to type"),
-    clear: typeParams.shape.clear.describe("Clear existing text before typing"),
+    ...applicationIdShape,
+    ...describeParams(typeParams.shape, {
+        widgetId: WIDGET_ID_DESCRIPTION,
+        text: "Text to type",
+        clear: "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"),
+    ...applicationIdShape,
+    ...describeParams(fireEventParams.shape, {
+        widgetId: WIDGET_ID_DESCRIPTION,
+        signal: "GTK4 signal name to emit",
+        args: "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.",
-    ),
+    ...describeParams(screenshotParams.shape, {
+        windowId: "Window ID to capture. If not specified, captures the first window.",
+        path:
+            "Absolute path to write the PNG to on the app's machine. If set, the screenshot is saved there " +
+            "in addition to being returned.",
+    }),
+};
+
+function describeParams<Shape extends Record<string, z.ZodType>>(
+    shape: Shape,
+    descriptions: { [Key in keyof Shape]: string },
+): Shape {
+    const described: [string, z.ZodType][] = Object.entries(shape).map(([key, schema]) => [
+        key,
+        schema.describe(descriptions[key as keyof Shape]),
+    ]);
+
+    return Object.fromEntries(described) as Shape;
+}
+
+const connectStdio = async (mcpServer: McpServer, stop: () => Promise<void>): Promise<void> => {
+    const transport = new StdioServerTransport();
+    process.stdin.on("end", () => void stop());
+    process.stdin.on("close", () => void stop());
+    await mcpServer.connect(transport);
 };
 
 const logSocketError = (event: Event): void => {
@@ -175,6 +232,32 @@ const screenshotTool = (appRouter: AppRouter): Tool =>
         },
     });
 
+const widgetPropsTool = (appRouter: AppRouter): Tool =>
+    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 same summary for its descendants. The subtree is bounded " +
+            `twice: ${String(DEFAULT_SUBTREE_DEPTH)} levels deep unless \`maxDepth\` says otherwise, and ` +
+            `${String(MAX_SUBTREE_WIDGETS)} widgets in all, filled breadth first. Wherever either bound ` +
+            "cut a branch, that widget carries `hiddenChildren`, the count of its own direct children left " +
+            "out rather than of everything below them; call again with that widget's ID to drill in, or " +
+            "use `gtkx_get_widget_tree` for a wider map. Pass `properties` to read GObject properties too; " +
+            "they come back first in the payload, each under its canonical kebab-case name as " +
+            "`{type, value}`, where an enum or flags value is its GType value name, a 64-bit integer a " +
+            "decimal string, and an object its GType name plus `widgetId` when it is a widget. Asking for " +
+            "a property the widget does not have fails; a value that cannot be marshalled carries a `note` " +
+            "instead.",
+        inputSchema: widgetPropsShape,
+        handler: async ({ applicationId, ...params }) => {
+            const result = await appRouter.sendToApp(applicationId, "widget.getProps", params);
+
+            return textContent(JSON.stringify(result, null, 2));
+        },
+    });
+
 function buildInspectionTools(appRouter: AppRouter): Tool[] {
     return [
         listAppsTool(appRouter),
@@ -201,7 +284,10 @@ function buildInspectionTools(appRouter: AppRouter): Tool[] {
             title: "Query widgets",
             kind: "readOnly",
             description:
-                "Find widgets by role, text, name, or label. Returns matching widgets with their IDs and properties.",
+                "Find widgets by role, text, name, or label. Returns each match with its ID and the same " +
+                "fixed summary `gtkx_get_widget_props` returns, with no descendants: a match that has " +
+                "children carries `hiddenChildren`, the count of its direct children left out. Read a " +
+                "match's subtree with `gtkx_get_widget_props` or `gtkx_get_widget_tree`.",
             inputSchema: queryWidgetsShape,
             handler: async ({ applicationId, ...params }) => {
                 const result = await appRouter.sendToApp(applicationId, "widget.query", params);
@@ -209,21 +295,7 @@ function buildInspectionTools(appRouter: AppRouter): Tool[] {
                 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));
-            },
-        }),
+        widgetPropsTool(appRouter),
         screenshotTool(appRouter),
     ];
 }
@@ -234,7 +306,10 @@ function buildInteractionTools(appRouter: AppRouter): Tool[] {
             name: "gtkx_click",
             title: "Click widget",
             kind: "action",
-            description: "Click a widget. Works with buttons, checkboxes, and other interactive widgets.",
+            description:
+                "Click a widget through userEvent.click, with no special case per widget. Works with " +
+                "buttons, checkboxes, switches, list and grid rows, tree expanders, and column headers: a " +
+                "row is selected, an expander toggles its row's expansion, and a header sorts its column.",
             inputSchema: widgetIdShape,
             handler: async ({ applicationId, ...params }) => {
                 await appRouter.sendToApp(applicationId, "widget.click", params);
@@ -261,9 +336,9 @@ function buildInteractionTools(appRouter: AppRouter): Tool[] {
             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);
+                const result = await appRouter.sendToApp(applicationId, "widget.fireEvent", params);
 
-                return textContent("Fired event");
+                return textContent(JSON.stringify(result, null, 2));
             },
         }),
     ];
@@ -273,6 +348,44 @@ function buildTools(appRouter: AppRouter): Tool[] {
     return [...buildInspectionTools(appRouter), ...buildInteractionTools(appRouter)];
 }
 
+const registerTools = (mcpServer: McpServer, appRouter: AppRouter, provider: ReferenceProvider): void => {
+    for (const tool of [...buildTools(appRouter), ...buildReferenceTools(provider)]) {
+        registerTool(mcpServer, tool);
+    }
+};
+
+async function stopServer(state: ServerLifecycle): Promise<void> {
+    if (state.isStopped) {
+        return;
+    }
+
+    state.isStopped = true;
+    await state.socketServer.stop();
+    await state.mcpServer.close();
+}
+
+async function startServer(state: ServerLifecycle): Promise<void> {
+    if (state.isStopped) {
+        throw new Error("createMcpServer: a stopped server cannot be started again");
+    }
+
+    await state.socketServer.start();
+
+    if (state.isStarted) {
+        return;
+    }
+
+    state.isStarted = true;
+    log.info(`socket server listening on ${state.socketPath}`);
+    await connectStdio(state.mcpServer, () => stopServer(state));
+}
+
+const createServerHandle = (socketServer: SocketServer, mcpServer: McpServer, socketPath: string): McpServerHandle => {
+    const state: ServerLifecycle = { socketServer, mcpServer, socketPath, isStopped: false, isStarted: false };
+
+    return { start: () => startServer(state), stop: () => stopServer(state) };
+};
+
 const createMcpServer = (options: CreateMcpServerOptions): McpServerHandle => {
     const socketPath = options.socketPath ?? DEFAULT_SOCKET_PATH;
     const registry = new ConnectionRegistry();
@@ -290,35 +403,11 @@ const createMcpServer = (options: CreateMcpServerOptions): McpServerHandle => {
     });
 
     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);
-    }
-
+    const referenceProvider = createReferenceProvider({ getAppRoot: () => appRouter.getProjectRoot() });
+    registerTools(mcpServer, appRouter, referenceProvider);
     registerReferenceResources(mcpServer, referenceProvider);
-    let isStopped = false;
-
-    const stop = async (): Promise<void> => {
-        if (isStopped) {
-            return;
-        }
-
-        isStopped = true;
-        await socketServer.stop();
-        await mcpServer.close();
-    };
-
-    const start = async (): Promise<void> => {
-        await socketServer.start();
-        log.info(`socket server listening on ${socketPath}`);
-        const transport = new StdioServerTransport();
-        process.stdin.on("end", () => void stop());
-        process.stdin.on("close", () => void stop());
-        await mcpServer.connect(transport);
-    };
-
-    return { start, stop };
+
+    return createServerHandle(socketServer, mcpServer, socketPath);
 };
 
 async function main(): Promise<void> {
@@ -331,4 +420,4 @@ async function main(): Promise<void> {
     await server.start();
 }
 
-export { log, createMcpServer, main };
+export { log, main };