@gtkx/mcp 1.6.0 → 2.0.0-beta.10

package/src/app-router.ts

@@ -16,6 +16,7 @@ import { type AppInfo, RegisterParamsSchema } from "./protocol/schemas.js";
 
 type AppRegisteredEvent = CustomEvent<AppInfo>;
 type AppUnregisteredEvent = CustomEvent<string>;
+type PendingAppWait = { reject: (error: Error) => void };
 
 type RegisteredApp = {
     info: AppInfo;
@@ -24,6 +25,14 @@ type RegisteredApp = {
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 
+const routerStoppedError = (): Error => new Error("GTKX MCP server stopped while waiting for an application");
+
+const appWaitTimeoutError = (timeout: number): Error =>
+    new Error(
+        `Timeout waiting for app registration after ${String(timeout)}ms. ` +
+        "Make sure your GTKX app is running with 'gtkx dev'.",
+    );
+
 function appRegisteredEvent(info: AppInfo): AppRegisteredEvent {
     return new CustomEvent("appRegistered", { detail: info });
 }
@@ -43,6 +52,10 @@ class AppRouter extends EventTarget {
 
     private connections: AppConnections;
 
+    private pendingAppWaits: Set<PendingAppWait> = new Set();
+
+    private isDisposed = false;
+
     constructor(connections: AppConnections, options: { requestTimeout?: number } = {}) {
         super();
         this.connections = connections;
@@ -69,6 +82,10 @@ class AppRouter extends EventTarget {
     }
 
     private handleRequest(connection: ProtocolConnection, request: JSONRPCRequest): Promise<Result> {
+        if (this.isDisposed) {
+            return Promise.reject(routerStoppedError());
+        }
+
         if (request.method === "app.register") {
             return Promise.resolve(this.handleRegister(connection, request));
         }
@@ -134,6 +151,40 @@ class AppRouter extends EventTarget {
         this.dispatchEvent(appUnregisteredEvent(applicationId));
     }
 
+    private async waitForRegistration(applicationId: string | undefined, timeout: number): Promise<AppInfo> {
+        const controller = new AbortController();
+        const { promise, reject, resolve } = Promise.withResolvers<AppInfo>();
+        const rejectWait = (error: Error): void => {
+            controller.abort();
+            reject(error);
+        };
+        const pendingWait: PendingAppWait = { reject: rejectWait };
+        const timeoutId = setTimeout(() => {
+            rejectWait(appWaitTimeoutError(timeout));
+        }, timeout);
+
+        this.addEventListener(
+            "appRegistered",
+            (event) => {
+                const info = (event as AppRegisteredEvent).detail;
+
+                if (applicationId === undefined || info.applicationId === applicationId) {
+                    resolve(info);
+                }
+            },
+            { signal: controller.signal },
+        );
+        this.pendingAppWaits.add(pendingWait);
+
+        try {
+            return await promise;
+        } finally {
+            clearTimeout(timeoutId);
+            controller.abort();
+            this.pendingAppWaits.delete(pendingWait);
+        }
+    }
+
     getApps(): AppInfo[] {
         return this.apps.values().map((app) => app.info).toArray();
     }
@@ -152,36 +203,40 @@ class AppRouter extends EventTarget {
         return this.getDefaultApp()?.info.projectRoot;
     }
 
-    waitForApp(timeout: number = AppRouter.defaultWaitTimeout): Promise<AppInfo> {
-        const defaultApp = this.getDefaultApp();
+    dispose(): void {
+        if (this.isDisposed) {
+            return;
+        }
+
+        this.isDisposed = true;
+        const error = routerStoppedError();
 
-        if (defaultApp) {
-            return Promise.resolve(defaultApp.info);
+        for (const pendingWait of this.pendingAppWaits) {
+            pendingWait.reject(error);
         }
+    }
 
-        return new Promise((resolve, reject) => {
-            const timeoutId = setTimeout(() => {
-                this.removeEventListener("appRegistered", onRegister);
+    waitForApp(applicationId?: string, timeout: number = AppRouter.defaultWaitTimeout): Promise<AppInfo> {
+        if (this.isDisposed) {
+            return Promise.reject(routerStoppedError());
+        }
 
-                reject(
-                    new Error(
-                        `Timeout waiting for app registration after ${String(timeout)}ms. ` +
-                        "Make sure your GTKX app is running with 'gtkx dev'.",
-                    ),
-                );
-            }, timeout);
+        const app = applicationId === undefined ? this.getDefaultApp() : this.apps.get(applicationId);
 
-            const onRegister = (event: Event): void => {
-                clearTimeout(timeoutId);
-                this.removeEventListener("appRegistered", onRegister);
-                resolve((event as AppRegisteredEvent).detail);
-            };
+        if (app) {
+            return Promise.resolve(app.info);
+        }
 
-            this.addEventListener("appRegistered", onRegister);
-        });
+        return this.waitForRegistration(applicationId, timeout);
     }
 
-    async sendToApp<T>(applicationId: string | undefined, method: string, params?: RequestParams): Promise<T> {
+    async sendToApp<T>(
+        applicationId: string | undefined,
+        method: string,
+        params?: RequestParams,
+        waitTimeout?: number,
+    ): Promise<T> {
+        await this.waitForApp(applicationId, waitTimeout);
         const app = this.resolveTargetApp(applicationId);
 
         try {

package/src/internal.ts

@@ -6,7 +6,6 @@ export {
     widgetNotFoundError,
 } from "./protocol/errors.js";
 export {
-    DEFAULT_SOCKET_PATH,
     DEFAULT_SUBTREE_DEPTH,
     MAX_SUBTREE_WIDGETS,
     type ParamsSchema,
@@ -16,5 +15,9 @@ export {
     type ServerRequestParams,
     ServerRequestParamsSchemas,
 } from "./protocol/schemas.js";
+export {
+    MCP_SOCKET_PATH_ENV,
+    resolveMcpSocketPath,
+} from "./socket-path.js";
 export { ProtocolConnection } from "./transport.js";
 export type { JSONRPCRequest, Result } from "@modelcontextprotocol/sdk/types.js";

package/src/protocol/schemas.ts

@@ -1,5 +1,3 @@
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { z } from "zod";
 
 type SerializedWidget = {
@@ -130,12 +128,6 @@ const ServerRequestParamsSchemas: {
     "widget.screenshot": screenshotParams,
 };
 
-const DEFAULT_SOCKET_PATH: string = join(getRuntimeDir(), "gtkx-mcp.sock");
-
-function getRuntimeDir(): string {
-    return process.env.XDG_RUNTIME_DIR ?? tmpdir();
-}
-
 export {
     DEFAULT_SUBTREE_DEPTH,
     MAX_SUBTREE_WIDGETS,
@@ -148,7 +140,6 @@ export {
     fireEventParams,
     screenshotParams,
     ServerRequestParamsSchemas,
-    DEFAULT_SOCKET_PATH,
     type SerializedWidget,
     type SerializedProperty,
     type AppInfo,

package/src/reference.ts

@@ -1,6 +1,5 @@
 import { type ApiReference, type ApiSymbol, loadApiReference, resolveGirPath, resolveLibraries } from "@gtkx/codegen";
 import { loadConfig } from "@gtkx/config";
-import { resolveFuture } 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";
@@ -59,7 +58,7 @@ type ResourceServer = Pick<McpServer, "registerResource">;
 
 const FRESHNESS_INTERVAL_MS = 2000;
 const FAILURE_RETRY_MS = 5000;
-const CONFIG_EXTENSIONS = ["ts", "mts", "cts", "js", "mjs", "cjs", "json"];
+const CONFIG_EXTENSIONS = ["ts", "mts", "js", "mjs", "json"];
 
 const PROJECT_SOURCE_LABELS: Record<ProjectSource, string> = {
     argument: "requested with `projectRoot`",
@@ -80,8 +79,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. " +
@@ -97,13 +96,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)."),
 };
@@ -193,17 +192,11 @@ const loadReference = async (requestedRoot: string): Promise<LoadedReference> =>
         );
     }
 
-    const future = resolveFuture(config.future);
-    const libraries = resolveLibraries(config.libraries, girPath, future.isAdwaitaDefault);
+    const libraries = resolveLibraries(config.libraries);
 
     const reference = loadApiReference({
         libraries,
         girPath,
-        isByteArrayTyped: future.isByteArrayTyped,
-        isValueUnwrapped: future.isValueUnwrapped,
-        isFinishTrimmed: future.isFinishTrimmed,
-        isInoutInPlace: future.isInoutInPlace,
-        isTreeShaken: future.isTreeShaken,
     });
 
     const watched = [watchFile(resolve(root, configFile)), ...reference.girFiles.map((file) => watchFile(file))];
@@ -211,17 +204,13 @@ const loadReference = async (requestedRoot: string): Promise<LoadedReference> =>
     return { reference, root, watched };
 };
 
-const markFailed = async (entry: CacheEntry): Promise<void> => {
-    try {
-        await entry.pending;
-    } catch {
-        entry.failedAt = Date.now();
-    }
-};
-
 const startLoad = (cache: ReferenceCache, root: string): CacheEntry => {
     const entry: CacheEntry = { pending: loadReference(root), verifiedAt: Date.now(), failedAt: undefined };
-    void markFailed(entry);
+
+    void entry.pending.catch(() => {
+        entry.failedAt = Date.now();
+    });
+
     cache.set(root, entry);
 
     return entry;
@@ -259,11 +248,9 @@ const currentReference = async (cache: ReferenceCache, root: string): Promise<Lo
     return revalidate(cache, root, entry).pending;
 };
 
-const defaultWorkingDirectory = (): string => process.cwd();
-
 const createReferenceProvider = (options: ReferenceProviderOptions): ReferenceProvider => {
     const cache: ReferenceCache = new Map();
-    const getWorkingDirectory = options.getWorkingDirectory ?? defaultWorkingDirectory;
+    const getWorkingDirectory = options.getWorkingDirectory ?? (() => process.cwd());
 
     const resolve = (projectRoot?: string): ResolvedProject =>
         resolveProject(getWorkingDirectory(), options.getAppRoot, projectRoot);
@@ -308,23 +295,12 @@ const scopedResult = async (
 const formatCandidates = (candidates: ApiSymbol[]): string =>
     candidates.map((candidate) => `- ${candidate.namespace}.${candidate.name} (${candidate.kind})`).join("\n");
 
-const buildSearchOptions = (args: ToolArgs<typeof searchApiShape>): SearchOptions => {
-    const options: SearchOptions = { query: args.query };
-
-    if (args.namespace !== undefined) {
-        options.namespace = args.namespace;
-    }
-
-    if (args.kind !== undefined) {
-        options.kinds = [args.kind];
-    }
-
-    if (args.limit !== undefined) {
-        options.limit = args.limit;
-    }
-
-    return options;
-};
+const buildSearchOptions = (args: ToolArgs<typeof searchApiShape>): SearchOptions => ({
+    query: args.query,
+    ...(args.namespace !== undefined && { namespace: args.namespace }),
+    ...(args.kind !== undefined && { kinds: [args.kind] }),
+    ...(args.limit !== undefined && { limit: args.limit }),
+});
 
 const listApiResult = (reference: ReferenceApi, namespace: string | undefined): CallToolResult => {
     if (namespace === undefined) {
@@ -378,8 +354,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)),
@@ -391,7 +368,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)),
@@ -403,7 +380,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,
@@ -431,9 +408,6 @@ const withLoadFallback = async <T>(load: () => Promise<T>, fallback: T): Promise
     }
 };
 
-const namesStartingWith = (names: string[], value: string): string[] =>
-    names.filter((name) => name.toLowerCase().startsWith(value.toLowerCase()));
-
 const completeNames = (
     provider: ReferenceProvider,
     value: string,
@@ -442,7 +416,7 @@ const completeNames = (
     withLoadFallback(async () => {
         const { reference } = await provider.get();
 
-        return namesStartingWith(collect(reference), value);
+        return collect(reference).filter((name) => name.toLowerCase().startsWith(value.toLowerCase()));
     }, []);
 
 const namespaceCompleter =
@@ -488,7 +462,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) => {
@@ -524,7 +498,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) => {
@@ -555,7 +529,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",
         },