@gtkx/mcp 1.6.0 → 2.0.0-beta.10

package/src/server.ts

@@ -12,7 +12,6 @@ import { type AppRegisteredEvent, AppRouter, type AppUnregisteredEvent } from ".
 import { ConnectionRegistry } from "./connection-registry.js";
 import {
     type AppInfo,
-    DEFAULT_SOCKET_PATH,
     DEFAULT_SUBTREE_DEPTH,
     fireEventParams,
     MAX_SUBTREE_WIDGETS,
@@ -29,6 +28,7 @@ import {
     type ReferenceProvider,
     registerReferenceResources,
 } from "./reference.js";
+import { resolveMcpSocketAddress } from "./socket-path.js";
 import { SocketServer } from "./socket-server.js";
 import { selectTools } from "./tool-filter.js";
 import { defineTool, imageContent, registerTool, textContent, textError, type Tool } from "./tool.js";
@@ -53,9 +53,11 @@ type McpServerHandle = {
 type ServerLifecycle = {
     socketServer: SocketServer;
     mcpServer: McpServer;
+    appRouter: AppRouter;
     socketPath: string;
-    isStopped: boolean;
-    isStarted: boolean;
+    isStopRequested: boolean;
+    startup: Promise<void> | null;
+    shutdown: Promise<void> | null;
 };
 
 type AppWindow = { id: string; title: string | null };
@@ -68,21 +70,29 @@ const DEFAULT_SETTINGS: McpSettings = { tools: [], isReadOnly: false };
 const INSTRUCTIONS =
     "The widget tools drive a GTKX app running under `gtkx dev`: they read " +
     "its live widget tree, query it by accessible role and name, click and type, and capture screenshots. " +
-    "They fail until an app is running, so start `gtkx dev` first. The reference tools answer from the " +
+    "They wait briefly for a starting app, so start `gtkx dev` before or alongside a widget request. " +
+    "The reference tools answer from the " +
     "bindings generated for a specific project, so they describe that project's GIR libraries rather than " +
-    "GTK in general; prefer them over recalled GTK knowledge, which is usually C, PyGObject or GJS and " +
-    "does not apply here.\n\n" +
+    "the GNOME platform in general; prefer them over recalled Adwaita or GTK knowledge, which is usually C, " +
+    "PyGObject or GJS and does not apply here.\n\n" +
     "Widget IDs are valid only while the widget is mounted. After a dialog closes, a list re-renders, or " +
     "fast refresh patches a component, re-read the tree or re-run the query instead of reusing an ID.";
 
-const APPLICATION_ID_DESCRIPTION = "Application ID to query. If not specified, uses the first connected app.";
+const APPLICATION_ID_DESCRIPTION =
+    "Application ID to query. If not specified, uses the first connected app. The tool waits briefly for the " +
+    "requested app to register.";
+
+const APP_TIMEOUT_DESCRIPTION = "Milliseconds to wait for the requested app to register (default: 10000).";
 
 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 applicationIdShape = {
+    applicationId: z.string().optional().describe(APPLICATION_ID_DESCRIPTION),
+    appTimeout: z.number().int().nonnegative().optional().describe(APP_TIMEOUT_DESCRIPTION),
+};
 
 const widgetIdShape = {
     ...applicationIdShape,
@@ -148,7 +158,7 @@ const fireEventShape = {
     ...applicationIdShape,
     ...describeParams(fireEventParams.shape, {
         widgetId: WIDGET_ID_DESCRIPTION,
-        signal: "GTK4 signal name to emit",
+        signal: "GObject signal name to emit",
         args: "Arguments to pass to the signal",
     }),
 };
@@ -220,11 +230,13 @@ const listAppsTool = (appRouter: AppRouter): Tool =>
         name: "gtkx_list_apps",
         title: "List apps",
         kind: "readOnly",
-        description: "List all connected GTKX applications and their open windows.",
+        description:
+            "List connected GTKX applications and their open windows. " +
+            "Returns the current snapshot immediately unless waitForApps is true.",
         inputSchema: listAppsShape,
         handler: async ({ waitForApps, timeout }) => {
             if (waitForApps && !appRouter.hasConnectedApps()) {
-                await appRouter.waitForApp(timeout);
+                await appRouter.waitForApp(undefined, timeout);
             }
 
             const apps = appRouter.getApps();
@@ -266,11 +278,12 @@ const screenshotTool = (appRouter: AppRouter): Tool =>
             "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, returnImage, ...params }) => {
+        handler: async ({ applicationId, appTimeout, returnImage, ...params }) => {
             const result = await appRouter.sendToApp<{ data: string; mimeType: string; savedPath?: string }>(
                 applicationId,
                 "widget.screenshot",
                 params,
+                appTimeout,
             );
 
             return screenshotResult(result, returnImage !== false);
@@ -296,8 +309,8 @@ const widgetPropsTool = (appRouter: AppRouter): Tool =>
             "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);
+        handler: async ({ applicationId, appTimeout, ...params }) => {
+            const result = await appRouter.sendToApp(applicationId, "widget.getProps", params, appTimeout);
 
             return textContent(JSON.stringify(result, null, 2));
         },
@@ -315,11 +328,11 @@ function buildInspectionTools(appRouter: AppRouter): Tool[] {
                 "types, roles, and properties. For large apps, pass `maxDepth` for a shallow overview and/or " +
                 "`rootId` to render just one subtree instead of the whole (possibly truncated) tree.",
             inputSchema: treeShape,
-            handler: async ({ applicationId, rootId, maxDepth }) => {
+            handler: async ({ applicationId, appTimeout, rootId, maxDepth }) => {
                 const result = await appRouter.sendToApp<{ tree: string }>(applicationId, "widget.getTree", {
                     rootId,
                     maxDepth,
-                });
+                }, appTimeout);
 
                 return textContent(result.tree);
             },
@@ -334,8 +347,8 @@ function buildInspectionTools(appRouter: AppRouter): Tool[] {
                 "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);
+            handler: async ({ applicationId, appTimeout, ...params }) => {
+                const result = await appRouter.sendToApp(applicationId, "widget.query", params, appTimeout);
 
                 return textContent(JSON.stringify(result, null, 2));
             },
@@ -356,8 +369,8 @@ function buildInteractionTools(appRouter: AppRouter): Tool[] {
                 "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);
+            handler: async ({ applicationId, appTimeout, ...params }) => {
+                await appRouter.sendToApp(applicationId, "widget.click", params, appTimeout);
 
                 return textContent("Clicked");
             },
@@ -368,8 +381,8 @@ function buildInteractionTools(appRouter: AppRouter): Tool[] {
             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);
+            handler: async ({ applicationId, appTimeout, ...params }) => {
+                await appRouter.sendToApp(applicationId, "widget.type", params, appTimeout);
 
                 return textContent("Typed text");
             },
@@ -378,10 +391,10 @@ function buildInteractionTools(appRouter: AppRouter): Tool[] {
             name: "gtkx_fire_event",
             title: "Fire event",
             kind: "action",
-            description: "Emit a GTK4 signal on a widget. Use this for custom interactions.",
+            description: "Emit a GObject signal on a widget. Use this for custom interactions.",
             inputSchema: fireEventShape,
-            handler: async ({ applicationId, ...params }) => {
-                const result = await appRouter.sendToApp(applicationId, "widget.fireEvent", params);
+            handler: async ({ applicationId, appTimeout, ...params }) => {
+                const result = await appRouter.sendToApp(applicationId, "widget.fireEvent", params, appTimeout);
 
                 return textContent(JSON.stringify(result, null, 2));
             },
@@ -410,42 +423,97 @@ const registerTools = (
     }
 };
 
-async function stopServer(state: ServerLifecycle): Promise<void> {
-    if (state.isStopped) {
-        return;
+const stoppedServerError = (): Error => new Error("createMcpServer: a stopped server cannot be started again");
+
+const wasStopRequested = (state: ServerLifecycle): boolean => state.isStopRequested;
+
+function stopServer(state: ServerLifecycle): Promise<void> {
+    if (state.shutdown !== null) {
+        return state.shutdown;
     }
 
-    state.isStopped = true;
-    await state.socketServer.stop();
-    await state.mcpServer.close();
+    state.isStopRequested = true;
+    state.appRouter.dispose();
+    const startup = state.startup;
+    const shutdown = (async (): Promise<void> => {
+        if (startup !== null) {
+            await Promise.allSettled([startup]);
+        }
+
+        await state.socketServer.stop();
+        await state.mcpServer.close();
+    })();
+
+    state.shutdown = shutdown;
+
+    return shutdown;
 }
 
-async function startServer(state: ServerLifecycle): Promise<void> {
-    if (state.isStopped) {
-        throw new Error("createMcpServer: a stopped server cannot be started again");
+function startServer(state: ServerLifecycle): Promise<void> {
+    if (wasStopRequested(state)) {
+        return Promise.reject(stoppedServerError());
     }
 
-    await state.socketServer.start();
-
-    if (state.isStarted) {
-        return;
+    if (state.startup !== null) {
+        return state.startup;
     }
 
-    state.isStarted = true;
-    log.info(`socket server listening on ${state.socketPath}`);
-    await connectStdio(state.mcpServer, () => stopServer(state));
+    const startup = (async (): Promise<void> => {
+        try {
+            await state.socketServer.start();
+
+            if (wasStopRequested(state)) {
+                return;
+            }
+
+            log.info(`socket server listening on ${state.socketPath}`);
+            await connectStdio(state.mcpServer, () => stopServer(state));
+        } catch (error) {
+            if (!wasStopRequested(state)) {
+                state.isStopRequested = true;
+                state.appRouter.dispose();
+                await state.socketServer.stop();
+                await state.mcpServer.close();
+            }
+
+            throw error;
+        }
+    })();
+
+    state.startup = startup;
+
+    return startup;
 }
 
-const createServerHandle = (socketServer: SocketServer, mcpServer: McpServer, socketPath: string): McpServerHandle => {
-    const state: ServerLifecycle = { socketServer, mcpServer, socketPath, isStopped: false, isStarted: false };
+const createServerHandle = (
+    socketServer: SocketServer,
+    mcpServer: McpServer,
+    appRouter: AppRouter,
+    socketPath: string,
+): McpServerHandle => {
+    const state: ServerLifecycle = {
+        socketServer,
+        mcpServer,
+        appRouter,
+        socketPath,
+        isStopRequested: false,
+        startup: null,
+        shutdown: null,
+    };
 
     return { start: () => startServer(state), stop: () => stopServer(state) };
 };
 
 const createMcpServer = (options: CreateMcpServerOptions): McpServerHandle => {
-    const socketPath = options.socketPath ?? DEFAULT_SOCKET_PATH;
+    const socketAddress = resolveMcpSocketAddress(options.socketPath);
+    const socketPath = socketAddress.path;
+
+    if (socketAddress.fallbackDirectory !== null) {
+        log.warn(`MCP socket path exceeds the safe Unix byte budget; using private fallback ${socketPath}`);
+    }
+
     const registry = new ConnectionRegistry();
-    const socketServer = new SocketServer(registry, socketPath);
+    const socketServer = new SocketServer(registry, socketAddress);
     const appRouter = new AppRouter(registry);
     registry.addEventListener("error", logSocketError);
 
@@ -463,7 +531,7 @@ const createMcpServer = (options: CreateMcpServerOptions): McpServerHandle => {
     registerTools(mcpServer, appRouter, referenceProvider, options.settings ?? DEFAULT_SETTINGS);
     registerReferenceResources(mcpServer, referenceProvider);
 
-    return createServerHandle(socketServer, mcpServer, socketPath);
+    return createServerHandle(socketServer, mcpServer, appRouter, socketPath);
 };
 
 const configuredSettings = async (cwd: string): Promise<McpSettings> => {

package/src/socket-path.ts

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { lstatSync, mkdirSync, rmdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+type McpSocketAddress = {
+    path: string;
+    fallbackDirectory: string | null;
+};
+
+const MCP_SOCKET_PATH_ENV = "GTKX_MCP_SOCKET_PATH";
+const SOCKET_NAME = "gtkx-mcp.sock";
+const SOCKET_PATH_BYTE_LIMIT = 100;
+const SHORT_SOCKET_ROOT = "/tmp";
+
+const socketCandidate = (): string =>
+    process.env[MCP_SOCKET_PATH_ENV] ?? join(process.env.XDG_RUNTIME_DIR ?? tmpdir(), SOCKET_NAME);
+
+const currentUserId = (): number => {
+    const getuid = process.getuid;
+
+    if (getuid === undefined) {
+        throw new Error("GTKX MCP Unix sockets require a platform with user IDs");
+    }
+
+    return getuid();
+};
+
+const verifyPrivateDirectory = (directory: string, userId: number): void => {
+    const entry = lstatSync(directory);
+
+    if (!entry.isDirectory() || entry.uid !== userId || (entry.mode & 0o777) !== 0o700) {
+        throw new Error(`GTKX MCP fallback socket directory is not private: ${directory}`);
+    }
+};
+
+const ensurePrivateDirectory = (directory: string, userId: number): void => {
+    try {
+        mkdirSync(directory, { mode: 0o700 });
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+            throw error;
+        }
+    }
+
+    verifyPrivateDirectory(directory, userId);
+};
+
+const fallbackAddress = (candidate: string): McpSocketAddress => {
+    const userId = currentUserId();
+    const digest = createHash("sha256").update(candidate).digest("hex").slice(0, 24);
+    const fallbackDirectory = join(SHORT_SOCKET_ROOT, `gtkx-mcp-${String(userId)}-${digest}`);
+
+    try {
+        verifyPrivateDirectory(fallbackDirectory, userId);
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+            throw error;
+        }
+    }
+
+    return { path: join(fallbackDirectory, "socket"), fallbackDirectory };
+};
+
+const resolveMcpSocketAddress = (providedPath?: string): McpSocketAddress => {
+    const candidate = providedPath ?? socketCandidate();
+
+    return Buffer.byteLength(candidate) <= SOCKET_PATH_BYTE_LIMIT
+        ? { path: candidate, fallbackDirectory: null }
+        : fallbackAddress(candidate);
+};
+
+const resolveMcpSocketPath = (providedPath?: string): string => resolveMcpSocketAddress(providedPath).path;
+
+const prepareMcpSocketAddress = (address: McpSocketAddress): void => {
+    if (address.fallbackDirectory !== null) {
+        ensurePrivateDirectory(address.fallbackDirectory, currentUserId());
+    }
+};
+
+const cleanupMcpSocketAddress = (address: McpSocketAddress): void => {
+    const directory = address.fallbackDirectory;
+
+    if (directory === null) {
+        return;
+    }
+
+    try {
+        verifyPrivateDirectory(directory, currentUserId());
+        rmdirSync(directory);
+    } catch {
+        return;
+    }
+};
+
+export {
+    cleanupMcpSocketAddress,
+    MCP_SOCKET_PATH_ENV,
+    prepareMcpSocketAddress,
+    resolveMcpSocketAddress,
+    resolveMcpSocketPath,
+    type McpSocketAddress,
+};

package/src/socket-server.ts

@@ -3,11 +3,16 @@ import * as fs from "node:fs";
 import * as net from "node:net";
 import { basename, dirname, join, resolve as resolvePath } from "node:path";
 import type { ConnectionRegistry } from "./connection-registry.js";
-import { DEFAULT_SOCKET_PATH } from "./protocol/schemas.js";
+import {
+    cleanupMcpSocketAddress,
+    type McpSocketAddress,
+    prepareMcpSocketAddress,
+    resolveMcpSocketAddress,
+} from "./socket-path.js";
 import { connectionErrorEvent } from "./transport.js";
 
 type ProbeOutcome = { kind: "live" } | { kind: "unknown"; code: string } | { kind: "vacant" };
-type PathVerdict = ProbeOutcome | { kind: "directory" };
+type PathVerdict = ProbeOutcome | { kind: "invalid" };
 type ClaimOutcome = "occupied" | "published";
 
 const PROBE_TIMEOUT_MS = 1000;
@@ -75,12 +80,6 @@ const acquireClaimLock = async (socketPath: string): Promise<net.Server | null>
     return lock;
 };
 
-const releaseClaimLock = async (lock: net.Server | null): Promise<void> => {
-    if (lock) {
-        await closeServer(lock);
-    }
-};
-
 const withClaimLock = async <T>(socketPath: string, action: () => Promise<T> | T): Promise<T> => {
     const lock = await acquireClaimLock(socketPath);
 
@@ -159,10 +158,10 @@ const undecidedOwnerError = (socketPath: string, code: string): Error =>
         "Retry, or delete the file by hand once no server is running.",
     );
 
-const directoryPathError = (socketPath: string): Error =>
+const invalidPathError = (socketPath: string): Error =>
     new Error(
-        `The GTKX MCP socket path ${socketPath} is a directory, not a socket. ` +
-        "Remove it, or point XDG_RUNTIME_DIR at a directory where GTKX can create its socket.",
+        `The GTKX MCP socket path ${socketPath} exists and is not a socket. ` +
+        "Move it, or point XDG_RUNTIME_DIR at a directory where GTKX can create its socket.",
     );
 
 const listenFailureError = (socketPath: string, code: string): Error =>
@@ -184,8 +183,8 @@ const clearStalePath = async (target: string): Promise<PathVerdict> => {
         return { kind: "vacant" };
     }
 
-    if (entry.isDirectory()) {
-        return { kind: "directory" };
+    if (!entry.isSocket()) {
+        return { kind: "invalid" };
     }
 
     const outcome = await probeUntilConclusive(target);
@@ -204,8 +203,8 @@ const requireVacantPath = async (socketPath: string): Promise<void> => {
         throw alreadyOwnedError(socketPath);
     }
 
-    if (verdict.kind === "directory") {
-        throw directoryPathError(socketPath);
+    if (verdict.kind === "invalid") {
+        throw invalidPathError(socketPath);
     }
 
     if (verdict.kind === "unknown") {
@@ -242,26 +241,18 @@ const publishSocket = async (privatePath: string, socketPath: string): Promise<n
     throw alreadyOwnedError(socketPath);
 };
 
-const releaseSocketPath = async (socketPath: string, inode: number): Promise<void> => {
-    const lock = await acquireClaimLock(socketPath);
-
-    try {
-        removeEntry(socketPath, inode);
-    } finally {
-        await releaseClaimLock(lock);
-    }
-};
-
 class SocketServer {
     private server: net.Server | null = null;
     private socketPath: string;
     private registry: ConnectionRegistry;
+    private address: McpSocketAddress;
     private boundInode: number | null = null;
     private startup: Promise<void> | null = null;
 
-    constructor(registry: ConnectionRegistry, socketPath: string = DEFAULT_SOCKET_PATH) {
+    constructor(registry: ConnectionRegistry, address: McpSocketAddress = resolveMcpSocketAddress()) {
         this.registry = registry;
-        this.socketPath = socketPath;
+        this.address = address;
+        this.socketPath = address.path;
     }
 
     private listen(privatePath: string): Promise<net.Server> {
@@ -294,21 +285,46 @@ class SocketServer {
     }
 
     private async bind(): Promise<void> {
+        prepareMcpSocketAddress(this.address);
         const privatePath = privatePathFor(this.socketPath);
         await clearStalePath(privatePath);
         const server = await this.listenPrivately(privatePath);
+        const privateInode = inodeFor(privatePath);
 
         try {
-            this.boundInode = await publishSocket(privatePath, this.socketPath);
+            if (privateInode === null) {
+                throw listenFailureError(this.socketPath, "ENOENT");
+            }
+
+            const publishedInode = await publishSocket(privatePath, this.socketPath);
+
+            if (publishedInode !== privateInode) {
+                throw listenFailureError(this.socketPath, "ESTALE");
+            }
+
+            this.boundInode = privateInode;
             this.server = server;
         } catch (error) {
             await closeServer(server);
+
+            if (privateInode !== null) {
+                removeEntry(privatePath, privateInode);
+                removeEntry(this.socketPath, privateInode);
+            }
+
             throw error;
         }
     }
 
     private open(): Promise<void> {
-        return withClaimLock(this.socketPath, () => this.bind());
+        return withClaimLock(this.socketPath, async () => {
+            try {
+                await this.bind();
+            } catch (error) {
+                cleanupMcpSocketAddress(this.address);
+                throw error;
+            }
+        });
     }
 
     private async settleStartup(): Promise<void> {
@@ -320,13 +336,23 @@ class SocketServer {
         }
     }
 
-    private async release(): Promise<void> {
+    private async release(server: net.Server): Promise<void> {
         const inode = this.boundInode;
-        this.boundInode = null;
 
-        if (inode !== null) {
-            await releaseSocketPath(this.socketPath, inode);
-        }
+        await withClaimLock(this.socketPath, async () => {
+            this.registry.dispose();
+            await closeServer(server);
+
+            try {
+                if (inode !== null) {
+                    removeEntry(this.socketPath, inode);
+                }
+            } finally {
+                cleanupMcpSocketAddress(this.address);
+            }
+        });
+
+        this.boundInode = null;
     }
 
     async start(): Promise<void> {
@@ -352,10 +378,8 @@ class SocketServer {
             return;
         }
 
+        await this.release(server);
         this.server = null;
-        this.registry.dispose();
-        await closeServer(server);
-        await this.release();
     }
 }