@gtkx/mcp 2.0.0-beta.1 → 2.0.0-beta.11

package/src/reference.ts

@@ -1,5 +1,20 @@
-import { type ApiReference, type ApiSymbol, loadApiReference, resolveGirPath, resolveLibraries } from "@gtkx/codegen";
+import {
+    type ApiReference,
+    type ApiSymbol,
+    loadApiReference,
+    mergeOmittedProps,
+    resolveGirPath,
+    resolveLibraries,
+} from "@gtkx/codegen";
+import { readBuiltinElementsForDocs } from "@gtkx/codegen/internal";
 import { loadConfig } from "@gtkx/config";
+import {
+    CONFIG_EXTENSIONS,
+    configDependenciesFor,
+    resolveAcceptedChildTypes,
+    resolveElementProps,
+    resolveOmittedProps,
+} from "@gtkx/config/internal";
 import { type McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type CallToolResult, ErrorCode, McpError, type ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import { existsSync, statSync } from "node:fs";
@@ -58,7 +73,7 @@ type ResourceServer = Pick<McpServer, "registerResource">;
 
 const FRESHNESS_INTERVAL_MS = 2000;
 const FAILURE_RETRY_MS = 5000;
-const CONFIG_EXTENSIONS = ["ts", "mts", "js", "mjs", "json"];
+const CONFIG_LOCATIONS = ["gtkx.config", ".config/gtkx", ".config/gtkx.config"];
 
 const PROJECT_SOURCE_LABELS: Record<ProjectSource, string> = {
     argument: "requested with `projectRoot`",
@@ -79,8 +94,8 @@ const SYMBOL_KIND = z.enum([
 ]);
 
 const SYMBOL_DESCRIPTION =
-    "Qualified symbol name (`Gtk.Button`, `Gtk.Orientation`, `GLib.idleAdd`), JSX element name (`GtkButton`), " +
-    "or bare symbol name when unambiguous (`Button`).";
+    "Qualified symbol name (`Adw.Toast`, `Gtk.Orientation`, `GLib.idleAdd`), JSX element name (`AdwToast`), " +
+    "or bare symbol name when unambiguous (`Toast`).";
 
 const PROJECT_ROOT_DESCRIPTION =
     "Directory of the GTKX project whose bindings to document, absolute or relative to the working directory. " +
@@ -96,13 +111,13 @@ const listApiShape = {
     namespace: z
         .string()
         .optional()
-        .describe("Namespace to list (e.g. `Gtk`, `Adw`, `Gio`). Omit for an overview of all namespaces."),
+        .describe("Namespace to list (e.g. `Adw`, `Gtk`, `Gio`). Omit for an overview of all namespaces."),
 };
 
 const searchApiShape = {
     ...projectRootShape,
     query: z.string().describe("Case-insensitive substring of a symbol name, e.g. `headerbar` or `orientation`."),
-    namespace: z.string().optional().describe("Restrict matches to one namespace (e.g. `Gtk`)."),
+    namespace: z.string().optional().describe("Restrict matches to one namespace (e.g. `Adw`)."),
     kind: SYMBOL_KIND.optional().describe("Restrict matches to one symbol kind."),
     limit: z.number().int().min(1).optional().describe("Maximum number of results (default: 20)."),
 };
@@ -128,10 +143,13 @@ const isFresh = (loaded: LoadedReference): boolean =>
         const current = watchFile(file.path);
 
         return current.mtimeMs === file.mtimeMs && current.size === file.size;
-    });
+    }) && loaded.reference.hasFreshInputs();
+
+const configCandidatePaths = (directory: string): string[] =>
+    CONFIG_LOCATIONS.flatMap((location) =>
+        CONFIG_EXTENSIONS.map((extension) => join(directory, `${location}${extension}`)));
 
-const hasConfigFile = (directory: string): boolean =>
-    CONFIG_EXTENSIONS.some((extension) => existsSync(join(directory, `gtkx.config.${extension}`)));
+const hasConfigFile = (directory: string): boolean => configCandidatePaths(directory).some((path) => existsSync(path));
 
 const findProjectRoot = (start: string): string | undefined => {
     const current = resolve(start);
@@ -172,7 +190,8 @@ const resolveProject = (
 };
 
 const loadReference = async (requestedRoot: string): Promise<LoadedReference> => {
-    const { config, configFile, root } = await loadConfig(requestedRoot);
+    const loaded = await loadConfig(requestedRoot);
+    const { config, root } = loaded;
 
     if (config.codegen === false) {
         throw new Error(
@@ -182,7 +201,7 @@ const loadReference = async (requestedRoot: string): Promise<LoadedReference> =>
         );
     }
 
-    const girPath = resolveGirPath(config.girPath);
+    const girPath = resolveGirPath(config.girPath, root);
 
     if (girPath.length === 0) {
         throw new Error(
@@ -193,13 +212,22 @@ const loadReference = async (requestedRoot: string): Promise<LoadedReference> =>
     }
 
     const libraries = resolveLibraries(config.libraries);
+    const builtin = await readBuiltinElementsForDocs();
 
     const reference = loadApiReference({
         libraries,
         girPath,
+        resolveFrom: root,
+        props: { ...builtin.props, ...resolveElementProps(config.elements) },
+        omittedProps: mergeOmittedProps(builtin.omittedProps, resolveOmittedProps(config.elements)),
+        acceptedChildTypes: { ...builtin.acceptedChildTypes, ...resolveAcceptedChildTypes(config.elements) },
     });
 
-    const watched = [watchFile(resolve(root, configFile)), ...reference.girFiles.map((file) => watchFile(file))];
+    const watched = [...new Set([
+        ...configDependenciesFor(loaded),
+        ...configCandidatePaths(root),
+        ...reference.inputFiles,
+    ])].map((file) => watchFile(file));
 
     return { reference, root, watched };
 };
@@ -354,8 +382,9 @@ const listApiTool = (provider: ReferenceProvider): Tool =>
         title: "List API reference",
         kind: "readOnly",
         description:
-            "List the project's generated GTK4 bindings API (`@gtkx/gi` and `@gtkx/jsx`). Without a namespace, " +
-            "returns every namespace with symbol counts; with a namespace, lists all of its symbols grouped by kind.",
+            "List the project's generated bindings API (`@gtkx/gi` and `@gtkx/jsx`), including Adwaita, " +
+            "GTK4, and its declared GIR libraries. Without a namespace, returns every namespace with symbol counts; " +
+            "with a namespace, lists all of its symbols grouped by kind.",
         inputSchema: listApiShape,
         handler: ({ namespace, projectRoot }) =>
             scopedResult(provider, projectRoot, (reference) => listApiResult(reference, namespace)),
@@ -367,7 +396,7 @@ const searchApiTool = (provider: ReferenceProvider): Tool =>
         title: "Search API reference",
         kind: "readOnly",
         description:
-            "Search the project's generated GTK4 bindings API by symbol name. Returns matching symbols with " +
+            "Search the project's generated bindings API by symbol name. Returns matching symbols with " +
             "their namespace, kind, and a one-line summary; fetch full pages with `gtkx_get_api_docs`.",
         inputSchema: searchApiShape,
         handler: (args) => scopedResult(provider, args.projectRoot, (reference) => searchApiResult(reference, args)),
@@ -379,7 +408,7 @@ const getApiDocsTool = (provider: ReferenceProvider): Tool =>
         title: "Get API docs",
         kind: "readOnly",
         description:
-            "Get the full reference page for one symbol of the project's generated GTK4 bindings: JSX elements " +
+            "Get the full reference page for one symbol of the project's generated bindings: JSX elements " +
             "(props, signals, methods) or `@gtkx/gi` classes, interfaces, records, enums, callbacks, aliases, " +
             "functions, and constants.",
         inputSchema: apiDocsShape,
@@ -461,7 +490,7 @@ const registerIndexResource = (server: ResourceServer, provider: ReferenceProvid
         "gtkx://reference/index",
         {
             title: "GTKX API reference index",
-            description: "Namespaces of the project's generated GTK4 bindings, with symbol and JSX element counts.",
+            description: "Namespaces of the project's generated bindings, with symbol and JSX element counts.",
             mimeType: "text/markdown",
         },
         async (uri) => {
@@ -497,7 +526,7 @@ const registerNamespaceResource = (server: ResourceServer, provider: ReferencePr
         }),
         {
             title: "GTKX namespace reference",
-            description: "All symbols of one namespace of the project's generated GTK4 bindings, grouped by kind.",
+            description: "All symbols of one namespace of the project's generated bindings, grouped by kind.",
             mimeType: "text/markdown",
         },
         async (uri, variables) => {
@@ -528,7 +557,7 @@ const registerSymbolResource = (server: ResourceServer, provider: ReferenceProvi
         {
             title: "GTKX symbol reference",
             description:
-                "Reference page for one symbol of the project's generated GTK4 bindings: a JSX element or a " +
+                "Reference page for one symbol of the project's generated bindings: a JSX element or a " +
                 "class, interface, record, enum, callback, alias, function, or constant.",
             mimeType: "text/markdown",
         },

package/src/server.ts

@@ -1,9 +1,11 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { loadConfig } from "@gtkx/config";
-import { type McpSettings, resolveMcpSettings } from "@gtkx/config/internal";
+import { configDependenciesFor, type McpSettings, resolveMcpSettings } from "@gtkx/config/internal";
 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 { existsSync } from "node:fs";
+import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { z } from "zod";
 import type { ConnectionErrorEvent } from "./transport.js";
@@ -12,7 +14,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 +30,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 +55,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 +72,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 +160,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",
     }),
 };
@@ -165,9 +177,8 @@ const screenshotShape = {
         .boolean()
         .optional()
         .describe(
-            "Whether to return the PNG as image content, true by default. Pass false together with `path` " +
-            "to save the screenshot and get back only where it landed, which keeps the image out of the " +
-            "conversation until something actually needs to look at it.",
+            "Return the PNG as image content (default: true). Set false with `path` to save the image " +
+            "and return only its file location.",
         ),
 };
 
@@ -220,11 +231,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 +279,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);
@@ -283,21 +297,17 @@ const widgetPropsTool = (appRouter: AppRouter): Tool =>
         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.",
+            "Read a widget's type, accessible role, name, text, sensitivity, visibility, CSS classes, " +
+            `and descendants. Defaults to ${String(DEFAULT_SUBTREE_DEPTH)} levels; \`maxDepth\` changes ` +
+            `the depth. Results contain at most ${String(MAX_SUBTREE_WIDGETS)} widgets, in breadth-first ` +
+            "order. `hiddenChildren` counts omitted direct children; query that widget's ID to expand it. " +
+            "Use `gtkx_get_widget_tree` for an overview. Requested GObject `properties` appear first, " +
+            "keyed by canonical kebab-case name with `{type, value}`. Enum/flags values use GType value " +
+            "names, 64-bit integers use decimal strings, and objects use their GType name plus `widgetId` " +
+            "for widgets. Unknown properties fail; values that cannot be converted include a `note`.",
         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 +325,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 +344,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));
             },
@@ -352,12 +362,12 @@ function buildInteractionTools(appRouter: AppRouter): Tool[] {
             title: "Click widget",
             kind: "action",
             description:
-                "Click a widget through userEvent.click, with no special case per widget. Works with " +
+                "Click a widget through userEvent.click. 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);
+            handler: async ({ applicationId, appTimeout, ...params }) => {
+                await appRouter.sendToApp(applicationId, "widget.click", params, appTimeout);
 
                 return textContent("Clicked");
             },
@@ -368,8 +378,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 +388,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 +420,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 +528,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> => {
@@ -471,7 +536,11 @@ const configuredSettings = async (cwd: string): Promise<McpSettings> => {
         const { config } = await loadConfig(cwd);
 
         return resolveMcpSettings(config);
-    } catch {
+    } catch (error) {
+        if (configDependenciesFor(error).some((path) => existsSync(resolve(cwd, path)))) {
+            throw error;
+        }
+
         return DEFAULT_SETTINGS;
     }
 };

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,
+};