@gtkx/mcp 0.11.1 → 0.12.0

package/README.md

@@ -0,0 +1,103 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/eugeniodepalo/gtkx/main/logo.svg" alt="GTKX" width="60" height="60">
+</p>
+
+<h1 align="center">GTKX</h1>
+
+<p align="center">
+  <strong>Build native GTK4 desktop applications with React and TypeScript.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@gtkx/react"><img src="https://img.shields.io/npm/v/@gtkx/react.svg" alt="npm version"></a>
+  <a href="https://github.com/eugeniodepalo/gtkx/actions"><img src="https://img.shields.io/github/actions/workflow/status/eugeniodepalo/gtkx/ci.yml" alt="CI"></a>
+  <a href="https://github.com/eugeniodepalo/gtkx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MPL--2.0-blue.svg" alt="License"></a>
+  <a href="https://github.com/eugeniodepalo/gtkx/discussions"><img src="https://img.shields.io/badge/discussions-GitHub-blue" alt="GitHub Discussions"></a>
+</p>
+
+---
+
+GTKX lets you write Linux desktop applications using React. Your components render as native GTK4 widgets through a Rust FFI bridge—no webviews, no Electron, just native performance with the developer experience you already know.
+
+## Quick Start
+
+```bash
+npx @gtkx/cli create my-app
+cd my-app
+npm run dev
+```
+
+## Example
+
+```tsx
+import {
+  GtkApplicationWindow,
+  GtkBox,
+  GtkButton,
+  GtkLabel,
+  quit,
+  render,
+} from "@gtkx/react";
+import * as Gtk from "@gtkx/ffi/gtk";
+import { useState } from "react";
+
+const App = () => {
+  const [count, setCount] = useState(0);
+
+  return (
+    <GtkApplicationWindow
+      title="Counter"
+      defaultWidth={300}
+      defaultHeight={200}
+      onCloseRequest={quit}
+    >
+      <GtkBox
+        orientation={Gtk.Orientation.VERTICAL}
+        spacing={20}
+        valign={Gtk.Align.CENTER}
+      >
+        <GtkLabel label={`Count: ${count}`} cssClasses={["title-1"]} />
+        <GtkButton label="Increment" onClicked={() => setCount((c) => c + 1)} />
+      </GtkBox>
+    </GtkApplicationWindow>
+  );
+};
+
+render(<App />, "com.example.counter");
+```
+
+## Features
+
+- **React 19** — Hooks, concurrent features, and the component model you know
+- **Native GTK4 widgets** — Real native controls, not web components in a webview
+- **Adwaita support** — Modern GNOME styling with Libadwaita components
+- **Hot Module Replacement** — Fast refresh during development
+- **TypeScript first** — Full type safety with auto-generated bindings
+- **CSS-in-JS styling** — Familiar styling patterns adapted for GTK
+- **Testing utilities** — Component testing similar to Testing Library
+
+## Examples
+
+Explore complete applications in the [`examples/`](./examples) directory:
+
+- **[gtk-demo](./examples/gtk-demo)** — Full replica of the official GTK demo app
+- **[hello-world](./examples/hello-world)** — Minimal application showing a counter
+- **[todo](./examples/todo)** — Full-featured todo application with Adwaita styling and testing
+- **[deploying](./examples/deploying)** — Example of packaging and distributing a GTKX app
+
+## Documentation
+
+Visit [https://eugeniodepalo.github.io/gtkx](https://eugeniodepalo.github.io/gtkx/) for the full documentation.
+
+## Contributing
+
+Contributions are welcome! Please see the [contributing guidelines](./CONTRIBUTING.md) and check out the [good first issues](https://github.com/eugeniodepalo/gtkx/labels/good%20first%20issue).
+
+## Community
+
+- [GitHub Discussions](https://github.com/eugeniodepalo/gtkx/discussions) — Questions, ideas, and general discussion
+- [Issue Tracker](https://github.com/eugeniodepalo/gtkx/issues) — Bug reports and feature requests
+
+## License
+
+[MPL-2.0](./LICENSE)

package/dist/cli.js

@@ -5,7 +5,6 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { ConnectionManager } from "./connection-manager.js";
-import { noAppConnectedError } from "./protocol/errors.js";
 import { DEFAULT_SOCKET_PATH } from "./protocol/types.js";
 import { SocketServer } from "./socket-server.js";
 const require = createRequire(import.meta.url);
@@ -13,6 +12,13 @@ const { version } = require("../package.json");
 const AppIdSchema = z.object({
     appId: z.string().optional().describe("App ID to query. If not specified, uses the first connected app."),
 });
+const ListAppsInputSchema = z.object({
+    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 GetWidgetTreeInputSchema = AppIdSchema;
 const QueryWidgetsInputSchema = AppIdSchema.extend({
     by: z.enum(["role", "text", "testId", "labelText"]).describe("Query type"),
@@ -41,7 +47,6 @@ const FireEventInputSchema = WidgetIdSchema.extend({
 });
 const TakeScreenshotInputSchema = AppIdSchema.extend({
     windowId: z.string().optional().describe("Window ID to capture. If not specified, captures the first window."),
-    format: z.enum(["png", "jpeg"]).optional().describe("Image format (default: png)"),
 });
 const tools = [
     {
@@ -49,7 +54,16 @@ const tools = [
         description: "List all connected GTKX applications",
         inputSchema: {
             type: "object",
-            properties: {},
+            properties: {
+                waitForApps: {
+                    type: "boolean",
+                    description: "If true, wait for at least one app to register before returning. Useful when app is still starting.",
+                },
+                timeout: {
+                    type: "number",
+                    description: "Timeout in milliseconds when waitForApps is true (default: 10000)",
+                },
+            },
             required: [],
         },
     },
@@ -190,7 +204,7 @@ const tools = [
     },
     {
         name: "gtkx_take_screenshot",
-        description: "Capture a screenshot of a window. Returns base64-encoded image data.",
+        description: "Capture a screenshot of a window. Returns base64-encoded PNG image data.",
         inputSchema: {
             type: "object",
             properties: {
@@ -202,11 +216,6 @@ const tools = [
                     type: "string",
                     description: "Window ID to capture. If not specified, captures the first window.",
                 },
-                format: {
-                    type: "string",
-                    enum: ["png", "jpeg"],
-                    description: "Image format (default: png)",
-                },
             },
             required: [],
         },
@@ -215,19 +224,20 @@ const tools = [
 async function main() {
     const socketServer = new SocketServer(DEFAULT_SOCKET_PATH);
     const connectionManager = new ConnectionManager(socketServer);
+    socketServer.on("error", (error) => {
+        const code = error.code;
+        if (code !== "EPIPE" && code !== "ECONNRESET") {
+            console.error("[gtkx] Socket error:", error.message);
+        }
+    });
     await socketServer.start();
-    console.error(`[gtkx-mcp] Socket server listening on ${DEFAULT_SOCKET_PATH}`);
+    console.error(`[gtkx] Socket server listening on ${DEFAULT_SOCKET_PATH}`);
     connectionManager.on("appRegistered", (appInfo) => {
-        console.error(`[gtkx-mcp] App registered: ${appInfo.appId} (PID: ${appInfo.pid})`);
+        console.error(`[gtkx] App registered: ${appInfo.appId} (PID: ${appInfo.pid})`);
     });
     connectionManager.on("appUnregistered", (appId) => {
-        console.error(`[gtkx-mcp] App unregistered: ${appId}`);
+        console.error(`[gtkx] App unregistered: ${appId}`);
     });
-    const requireConnectedApp = () => {
-        if (!connectionManager.hasConnectedApps()) {
-            throw noAppConnectedError();
-        }
-    };
     const server = new Server({
         name: "gtkx-mcp",
         version,
@@ -244,6 +254,23 @@ async function main() {
         try {
             switch (name) {
                 case "gtkx_list_apps": {
+                    const input = ListAppsInputSchema.parse(args);
+                    if (input.waitForApps && !connectionManager.hasConnectedApps()) {
+                        try {
+                            await connectionManager.waitForApp(input.timeout);
+                        }
+                        catch (error) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: error instanceof Error ? error.message : "Timeout waiting for app",
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                    }
                     const apps = connectionManager.getApps();
                     return {
                         content: [{ type: "text", text: JSON.stringify(apps, null, 2) }],
@@ -251,15 +278,13 @@ async function main() {
                 }
                 case "gtkx_get_widget_tree": {
                     const input = GetWidgetTreeInputSchema.parse(args);
-                    requireConnectedApp();
                     const result = await connectionManager.sendToApp(input.appId, "widget.getTree", {});
                     return {
-                        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                        content: [{ type: "text", text: result.tree }],
                     };
                 }
                 case "gtkx_query_widgets": {
                     const input = QueryWidgetsInputSchema.parse(args);
-                    requireConnectedApp();
                     const result = await connectionManager.sendToApp(input.appId, "widget.query", {
                         queryType: input.by,
                         value: input.value,
@@ -271,7 +296,6 @@ async function main() {
                 }
                 case "gtkx_get_widget_props": {
                     const input = GetWidgetPropsInputSchema.parse(args);
-                    requireConnectedApp();
                     const result = await connectionManager.sendToApp(input.appId, "widget.getProps", {
                         widgetId: input.widgetId,
                     });
@@ -281,7 +305,6 @@ async function main() {
                 }
                 case "gtkx_click": {
                     const input = ClickInputSchema.parse(args);
-                    requireConnectedApp();
                     await connectionManager.sendToApp(input.appId, "widget.click", {
                         widgetId: input.widgetId,
                     });
@@ -291,7 +314,6 @@ async function main() {
                 }
                 case "gtkx_type": {
                     const input = TypeInputSchema.parse(args);
-                    requireConnectedApp();
                     await connectionManager.sendToApp(input.appId, "widget.type", {
                         widgetId: input.widgetId,
                         text: input.text,
@@ -303,7 +325,6 @@ async function main() {
                 }
                 case "gtkx_fire_event": {
                     const input = FireEventInputSchema.parse(args);
-                    requireConnectedApp();
                     await connectionManager.sendToApp(input.appId, "widget.fireEvent", {
                         widgetId: input.widgetId,
                         signal: input.signal,
@@ -315,10 +336,8 @@ async function main() {
                 }
                 case "gtkx_take_screenshot": {
                     const input = TakeScreenshotInputSchema.parse(args);
-                    requireConnectedApp();
                     const result = await connectionManager.sendToApp(input.appId, "widget.screenshot", {
                         windowId: input.windowId,
-                        format: input.format,
                     });
                     return {
                         content: [
@@ -365,6 +384,6 @@ async function main() {
     process.on("SIGTERM", shutdown);
 }
 main().catch((error) => {
-    console.error("[gtkx-mcp] Fatal error:", error);
+    console.error("[gtkx] Fatal error:", error);
     process.exit(1);
 });

package/dist/connection-manager.d.ts

@@ -9,8 +9,14 @@ interface RegisteredApp {
     info: AppInfo;
     connection: AppConnection;
 }
+/**
+ * Manages connections between the MCP server and GTKX applications.
+ *
+ * Handles app registration, request routing, and connection lifecycle.
+ */
 export declare class ConnectionManager extends EventEmitter<ConnectionManagerEventMap> {
     private socketServer;
+    private static readonly DEFAULT_WAIT_TIMEOUT;
     private apps;
     private connectionToApp;
     private pendingRequests;
@@ -22,6 +28,14 @@ export declare class ConnectionManager extends EventEmitter<ConnectionManagerEve
     getApp(appId: string): AppInfo | undefined;
     hasConnectedApps(): boolean;
     getDefaultApp(): RegisteredApp | undefined;
+    /**
+     * Waits for at least one app to connect and register.
+     *
+     * @param timeout - Maximum time to wait in milliseconds (default: 10000)
+     * @returns Promise that resolves with the first registered app info
+     * @throws Error if timeout is reached before any app registers
+     */
+    waitForApp(timeout?: number): Promise<AppInfo>;
     sendToApp<T>(appId: string | undefined, method: string, params?: unknown): Promise<T>;
     cleanup(): void;
     private handleRequest;

package/dist/connection-manager.js

@@ -1,8 +1,14 @@
 import EventEmitter from "node:events";
 import { appNotFoundError, invalidRequestError, ipcTimeoutError, McpError, noAppConnectedError, } from "./protocol/errors.js";
 import { RegisterParamsSchema } from "./protocol/types.js";
+/**
+ * Manages connections between the MCP server and GTKX applications.
+ *
+ * Handles app registration, request routing, and connection lifecycle.
+ */
 export class ConnectionManager extends EventEmitter {
     socketServer;
+    static DEFAULT_WAIT_TIMEOUT = 10000;
     apps = new Map();
     connectionToApp = new Map();
     pendingRequests = new Map();
@@ -14,6 +20,9 @@ export class ConnectionManager extends EventEmitter {
         this.socketServer.on("request", (connection, request) => {
             this.handleRequest(connection, request);
         });
+        this.socketServer.on("response", (_connection, response) => {
+            this.handleResponse(response);
+        });
         this.socketServer.on("disconnection", (connection) => {
             this.handleDisconnection(connection);
         });
@@ -31,6 +40,32 @@ export class ConnectionManager extends EventEmitter {
         const first = this.apps.values().next();
         return first.done ? undefined : first.value;
     }
+    /**
+     * Waits for at least one app to connect and register.
+     *
+     * @param timeout - Maximum time to wait in milliseconds (default: 10000)
+     * @returns Promise that resolves with the first registered app info
+     * @throws Error if timeout is reached before any app registers
+     */
+    waitForApp(timeout = ConnectionManager.DEFAULT_WAIT_TIMEOUT) {
+        const defaultApp = this.getDefaultApp();
+        if (defaultApp) {
+            return Promise.resolve(defaultApp.info);
+        }
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                this.off("appRegistered", onRegister);
+                reject(new Error(`Timeout waiting for app registration after ${timeout}ms. ` +
+                    "Make sure your GTKX app is running with 'gtkx dev'."));
+            }, timeout);
+            const onRegister = (appInfo) => {
+                clearTimeout(timeoutId);
+                this.off("appRegistered", onRegister);
+                resolve(appInfo);
+            };
+            this.on("appRegistered", onRegister);
+        });
+    }
     async sendToApp(appId, method, params) {
         const app = appId ? this.apps.get(appId) : this.getDefaultApp();
         if (!app) {
@@ -55,7 +90,13 @@ export class ConnectionManager extends EventEmitter {
                 reject,
                 timeout,
             });
-            this.socketServer.send(app.connection.id, request);
+            const sent = this.socketServer.send(app.connection.id, request);
+            if (!sent) {
+                clearTimeout(timeout);
+                this.pendingRequests.delete(requestId);
+                reject(appNotFoundError(app.info.appId));
+                return;
+            }
         });
     }
     cleanup() {
@@ -74,16 +115,14 @@ export class ConnectionManager extends EventEmitter {
             this.handleUnregister(connection, request);
             return;
         }
-        this.handleResponse(request);
     }
-    handleResponse(message) {
-        const pending = this.pendingRequests.get(message.id);
+    handleResponse(response) {
+        const pending = this.pendingRequests.get(response.id);
         if (!pending) {
             return;
         }
         clearTimeout(pending.timeout);
-        this.pendingRequests.delete(message.id);
-        const response = message;
+        this.pendingRequests.delete(response.id);
         if (response.error) {
             const err = response.error;
             pending.reject(new McpError(err.code, err.message, err.data));

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { ConnectionManager } from "./connection-manager.js";
-export { McpError, McpErrorCode, methodNotFoundError, widgetNotFoundError, } from "./protocol/errors.js";
-export { type AppInfo, DEFAULT_SOCKET_PATH, type IpcError, type IpcMethod, type IpcRequest, type IpcResponse, type QueryOptions, type SerializedWidget, } from "./protocol/types.js";
+export { appNotFoundError, invalidRequestError, ipcTimeoutError, McpError, McpErrorCode, methodNotFoundError, noAppConnectedError, widgetNotFoundError, } from "./protocol/errors.js";
+export { type AppInfo, DEFAULT_SOCKET_PATH, getRuntimeDir, type IpcError, IpcErrorSchema, type IpcMessage, type IpcMethod, type IpcRequest, IpcRequestSchema, type IpcResponse, IpcResponseSchema, type QueryOptions, type SerializedWidget, } from "./protocol/types.js";
 export { type AppConnection, SocketServer } from "./socket-server.js";

package/dist/index.js

@@ -1,4 +1,4 @@
 export { ConnectionManager } from "./connection-manager.js";
-export { McpError, McpErrorCode, methodNotFoundError, widgetNotFoundError, } from "./protocol/errors.js";
-export { DEFAULT_SOCKET_PATH, } from "./protocol/types.js";
+export { appNotFoundError, invalidRequestError, ipcTimeoutError, McpError, McpErrorCode, methodNotFoundError, noAppConnectedError, widgetNotFoundError, } from "./protocol/errors.js";
+export { DEFAULT_SOCKET_PATH, getRuntimeDir, IpcErrorSchema, IpcRequestSchema, IpcResponseSchema, } from "./protocol/types.js";
 export { SocketServer } from "./socket-server.js";

package/dist/protocol/errors.d.ts

@@ -1,30 +1,92 @@
+/**
+ * Error codes for MCP protocol errors.
+ */
 export declare enum McpErrorCode {
+    /** Internal server error */
     INTERNAL_ERROR = 1000,
+    /** No GTKX application is connected */
     NO_APP_CONNECTED = 1001,
+    /** Requested application ID was not found */
     APP_NOT_FOUND = 1002,
+    /** Widget with specified ID was not found */
     WIDGET_NOT_FOUND = 1003,
+    /** Widget cannot be interacted with */
     WIDGET_NOT_INTERACTABLE = 1004,
+    /** Query timed out waiting for widget */
     QUERY_TIMEOUT = 1005,
+    /** Widget is not the expected type */
     INVALID_WIDGET_TYPE = 1006,
+    /** Screenshot capture failed */
     SCREENSHOT_FAILED = 1007,
+    /** IPC request timed out */
     IPC_TIMEOUT = 1008,
+    /** Failed to serialize data */
     SERIALIZATION_ERROR = 1009,
+    /** Request format is invalid */
     INVALID_REQUEST = 1010,
+    /** Requested method does not exist */
     METHOD_NOT_FOUND = 1011
 }
+/**
+ * Error class for MCP protocol errors.
+ *
+ * Contains an error code, message, and optional additional data.
+ */
 export declare class McpError extends Error {
+    /** The MCP error code */
     readonly code: McpErrorCode;
+    /** Additional error context */
     readonly data?: unknown;
     constructor(code: McpErrorCode, message: string, data?: unknown);
+    /**
+     * Converts the error to an IPC-compatible format.
+     *
+     * @returns Object suitable for IPC response error field
+     */
     toIpcError(): {
         code: number;
         message: string;
         data?: unknown;
     };
 }
+/**
+ * Creates an error for when no GTKX application is connected.
+ *
+ * @returns McpError with NO_APP_CONNECTED code
+ */
 export declare function noAppConnectedError(): McpError;
+/**
+ * Creates an error for when a requested app is not found.
+ *
+ * @param appId - The application ID that was not found
+ * @returns McpError with APP_NOT_FOUND code
+ */
 export declare function appNotFoundError(appId: string): McpError;
+/**
+ * Creates an error for when a widget is not found.
+ *
+ * @param widgetId - The widget ID that was not found
+ * @returns McpError with WIDGET_NOT_FOUND code
+ */
 export declare function widgetNotFoundError(widgetId: string): McpError;
+/**
+ * Creates an error for when an IPC request times out.
+ *
+ * @param timeout - The timeout duration in milliseconds
+ * @returns McpError with IPC_TIMEOUT code
+ */
 export declare function ipcTimeoutError(timeout: number): McpError;
+/**
+ * Creates an error for invalid request format.
+ *
+ * @param reason - Description of why the request is invalid
+ * @returns McpError with INVALID_REQUEST code
+ */
 export declare function invalidRequestError(reason: string): McpError;
+/**
+ * Creates an error for when a method is not found.
+ *
+ * @param method - The method name that was not found
+ * @returns McpError with METHOD_NOT_FOUND code
+ */
 export declare function methodNotFoundError(method: string): McpError;

package/dist/protocol/errors.js

@@ -1,20 +1,42 @@
+/**
+ * Error codes for MCP protocol errors.
+ */
 export var McpErrorCode;
 (function (McpErrorCode) {
+    /** Internal server error */
     McpErrorCode[McpErrorCode["INTERNAL_ERROR"] = 1000] = "INTERNAL_ERROR";
+    /** No GTKX application is connected */
     McpErrorCode[McpErrorCode["NO_APP_CONNECTED"] = 1001] = "NO_APP_CONNECTED";
+    /** Requested application ID was not found */
     McpErrorCode[McpErrorCode["APP_NOT_FOUND"] = 1002] = "APP_NOT_FOUND";
+    /** Widget with specified ID was not found */
     McpErrorCode[McpErrorCode["WIDGET_NOT_FOUND"] = 1003] = "WIDGET_NOT_FOUND";
+    /** Widget cannot be interacted with */
     McpErrorCode[McpErrorCode["WIDGET_NOT_INTERACTABLE"] = 1004] = "WIDGET_NOT_INTERACTABLE";
+    /** Query timed out waiting for widget */
     McpErrorCode[McpErrorCode["QUERY_TIMEOUT"] = 1005] = "QUERY_TIMEOUT";
+    /** Widget is not the expected type */
     McpErrorCode[McpErrorCode["INVALID_WIDGET_TYPE"] = 1006] = "INVALID_WIDGET_TYPE";
+    /** Screenshot capture failed */
     McpErrorCode[McpErrorCode["SCREENSHOT_FAILED"] = 1007] = "SCREENSHOT_FAILED";
+    /** IPC request timed out */
     McpErrorCode[McpErrorCode["IPC_TIMEOUT"] = 1008] = "IPC_TIMEOUT";
+    /** Failed to serialize data */
     McpErrorCode[McpErrorCode["SERIALIZATION_ERROR"] = 1009] = "SERIALIZATION_ERROR";
+    /** Request format is invalid */
     McpErrorCode[McpErrorCode["INVALID_REQUEST"] = 1010] = "INVALID_REQUEST";
+    /** Requested method does not exist */
     McpErrorCode[McpErrorCode["METHOD_NOT_FOUND"] = 1011] = "METHOD_NOT_FOUND";
 })(McpErrorCode || (McpErrorCode = {}));
+/**
+ * Error class for MCP protocol errors.
+ *
+ * Contains an error code, message, and optional additional data.
+ */
 export class McpError extends Error {
+    /** The MCP error code */
     code;
+    /** Additional error context */
     data;
     constructor(code, message, data) {
         super(message);
@@ -25,6 +47,11 @@ export class McpError extends Error {
             Error.captureStackTrace(this, McpError);
         }
     }
+    /**
+     * Converts the error to an IPC-compatible format.
+     *
+     * @returns Object suitable for IPC response error field
+     */
     toIpcError() {
         return {
             code: this.code,
@@ -33,21 +60,56 @@ export class McpError extends Error {
         };
     }
 }
+/**
+ * Creates an error for when no GTKX application is connected.
+ *
+ * @returns McpError with NO_APP_CONNECTED code
+ */
 export function noAppConnectedError() {
     return new McpError(McpErrorCode.NO_APP_CONNECTED, "No GTKX application connected. Start an app with 'gtkx dev' to connect.", { hint: "Run 'gtkx dev src/app.tsx' in your project directory" });
 }
+/**
+ * Creates an error for when a requested app is not found.
+ *
+ * @param appId - The application ID that was not found
+ * @returns McpError with APP_NOT_FOUND code
+ */
 export function appNotFoundError(appId) {
     return new McpError(McpErrorCode.APP_NOT_FOUND, `Application '${appId}' not found`, { appId });
 }
+/**
+ * Creates an error for when a widget is not found.
+ *
+ * @param widgetId - The widget ID that was not found
+ * @returns McpError with WIDGET_NOT_FOUND code
+ */
 export function widgetNotFoundError(widgetId) {
     return new McpError(McpErrorCode.WIDGET_NOT_FOUND, `Widget '${widgetId}' not found`, { widgetId });
 }
+/**
+ * Creates an error for when an IPC request times out.
+ *
+ * @param timeout - The timeout duration in milliseconds
+ * @returns McpError with IPC_TIMEOUT code
+ */
 export function ipcTimeoutError(timeout) {
     return new McpError(McpErrorCode.IPC_TIMEOUT, `IPC request timed out after ${timeout}ms`, { timeout });
 }
+/**
+ * Creates an error for invalid request format.
+ *
+ * @param reason - Description of why the request is invalid
+ * @returns McpError with INVALID_REQUEST code
+ */
 export function invalidRequestError(reason) {
     return new McpError(McpErrorCode.INVALID_REQUEST, `Invalid request: ${reason}`, { reason });
 }
+/**
+ * Creates an error for when a method is not found.
+ *
+ * @param method - The method name that was not found
+ * @returns McpError with METHOD_NOT_FOUND code
+ */
 export function methodNotFoundError(method) {
     return new McpError(McpErrorCode.METHOD_NOT_FOUND, `Method '${method}' not found`, { method });
 }

package/dist/protocol/types.d.ts

@@ -1,39 +1,116 @@
 import { z } from "zod";
+/**
+ * Zod schema for validating IPC requests.
+ */
 export declare const IpcRequestSchema: z.ZodObject<{
     id: z.ZodString;
     method: z.ZodString;
     params: z.ZodOptional<z.ZodUnknown>;
 }, "strip", z.ZodTypeAny, {
-    method: string;
     id: string;
+    method: string;
     params?: unknown;
 }, {
-    method: string;
     id: string;
+    method: string;
     params?: unknown;
 }>;
+/**
+ * An IPC request message.
+ */
 export type IpcRequest = z.infer<typeof IpcRequestSchema>;
+/**
+ * An IPC error object.
+ */
 export type IpcError = {
+    /** Error code */
     code: number;
+    /** Error message */
     message: string;
+    /** Additional error data */
     data?: unknown;
 };
-export type IpcResponse = {
+/**
+ * Zod schema for validating IPC errors.
+ */
+export declare const IpcErrorSchema: z.ZodObject<{
+    code: z.ZodNumber;
+    message: z.ZodString;
+    data: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    code: number;
+    message: string;
+    data?: unknown;
+}, {
+    code: number;
+    message: string;
+    data?: unknown;
+}>;
+/**
+ * Zod schema for validating IPC responses.
+ */
+export declare const IpcResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodNumber;
+        message: z.ZodString;
+        data: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        code: number;
+        message: string;
+        data?: unknown;
+    }, {
+        code: number;
+        message: string;
+        data?: unknown;
+    }>>;
+}, "strip", z.ZodTypeAny, {
     id: string;
     result?: unknown;
-    error?: IpcError;
-};
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    } | undefined;
+}, {
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    } | undefined;
+}>;
+/**
+ * An IPC response message.
+ */
+export type IpcResponse = z.infer<typeof IpcResponseSchema>;
+/**
+ * A serialized representation of a GTK widget for IPC transfer.
+ */
 export interface SerializedWidget {
+    /** Unique widget identifier */
     id: string;
+    /** Widget type name (e.g., "GtkButton") */
     type: string;
+    /** Accessible role */
     role: string;
+    /** Widget name (test ID) */
     name: string | null;
+    /** Accessible label */
     label: string | null;
+    /** Text content */
     text: string | null;
+    /** Whether the widget is sensitive (interactive) */
     sensitive: boolean;
+    /** Whether the widget is visible */
     visible: boolean;
+    /** CSS class names */
     cssClasses: string[];
+    /** Child widgets */
     children: SerializedWidget[];
+    /** Widget bounds in window coordinates */
     bounds?: {
         x: number;
         y: number;
@@ -41,21 +118,35 @@ export interface SerializedWidget {
         height: number;
     };
 }
+/**
+ * Information about a connected GTKX application.
+ */
 export type AppInfo = {
+    /** Application ID (e.g., "com.example.myapp") */
     appId: string;
+    /** Process ID */
     pid: number;
+    /** Open windows */
     windows: Array<{
         id: string;
         title: string | null;
     }>;
 };
+/**
+ * Options for widget queries.
+ */
 export type QueryOptions = {
+    /** Widget name to match */
     name?: string;
-    checked?: boolean;
-    expanded?: boolean;
+    /** Require exact match */
     exact?: boolean;
+    /** Query timeout in milliseconds */
     timeout?: number;
 };
+/**
+ * Zod schema for app registration parameters.
+ * @internal
+ */
 export declare const RegisterParamsSchema: z.ZodObject<{
     appId: z.ZodString;
     pid: z.ZodNumber;
@@ -66,6 +157,21 @@ export declare const RegisterParamsSchema: z.ZodObject<{
     appId: string;
     pid: number;
 }>;
+/**
+ * Available IPC methods.
+ */
 export type IpcMethod = "app.register" | "app.unregister" | "widget.getTree" | "widget.query" | "widget.getProps" | "widget.click" | "widget.type" | "widget.fireEvent" | "widget.screenshot";
+/**
+ * Union type for any IPC message (request or response).
+ */
 export type IpcMessage = IpcRequest | IpcResponse;
-export declare const DEFAULT_SOCKET_PATH = "/tmp/gtkx-mcp.sock";
+/**
+ * Gets the XDG runtime directory or falls back to system temp.
+ *
+ * @returns Path to the runtime directory
+ */
+export declare const getRuntimeDir: () => string;
+/**
+ * Default path for the MCP socket file.
+ */
+export declare const DEFAULT_SOCKET_PATH: string;

package/dist/protocol/types.js

@@ -1,11 +1,45 @@
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { z } from "zod";
+/**
+ * Zod schema for validating IPC requests.
+ */
 export const IpcRequestSchema = z.object({
     id: z.string(),
     method: z.string(),
     params: z.unknown().optional(),
 });
+/**
+ * Zod schema for validating IPC errors.
+ */
+export const IpcErrorSchema = z.object({
+    code: z.number(),
+    message: z.string(),
+    data: z.unknown().optional(),
+});
+/**
+ * Zod schema for validating IPC responses.
+ */
+export const IpcResponseSchema = z.object({
+    id: z.string(),
+    result: z.unknown().optional(),
+    error: IpcErrorSchema.optional(),
+});
+/**
+ * Zod schema for app registration parameters.
+ * @internal
+ */
 export const RegisterParamsSchema = z.object({
     appId: z.string(),
     pid: z.number(),
 });
-export const DEFAULT_SOCKET_PATH = "/tmp/gtkx-mcp.sock";
+/**
+ * Gets the XDG runtime directory or falls back to system temp.
+ *
+ * @returns Path to the runtime directory
+ */
+export const getRuntimeDir = () => process.env.XDG_RUNTIME_DIR ?? tmpdir();
+/**
+ * Default path for the MCP socket file.
+ */
+export const DEFAULT_SOCKET_PATH = join(getRuntimeDir(), "gtkx-mcp.sock");

package/dist/socket-server.d.ts

@@ -1,17 +1,29 @@
 import EventEmitter from "node:events";
 import * as net from "node:net";
-import { type IpcMessage, type IpcRequest } from "./protocol/types.js";
+import { type IpcMessage, type IpcRequest, type IpcResponse } from "./protocol/types.js";
 type SocketServerEventMap = {
     connection: [AppConnection];
     disconnection: [AppConnection];
     request: [AppConnection, IpcRequest];
+    response: [AppConnection, IpcResponse];
     error: [Error];
 };
+/**
+ * Represents a connected application.
+ */
 export interface AppConnection {
+    /** Unique connection identifier */
     id: string;
+    /** The underlying socket */
     socket: net.Socket;
+    /** Buffer for incomplete messages */
     buffer: string;
 }
+/**
+ * Unix domain socket server for MCP communication.
+ *
+ * Manages connections from GTKX applications and handles IPC messaging.
+ */
 export declare class SocketServer extends EventEmitter<SocketServerEventMap> {
     private server;
     private connections;

package/dist/socket-server.js

@@ -2,7 +2,12 @@ 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, IpcRequestSchema, } from "./protocol/types.js";
+import { DEFAULT_SOCKET_PATH, IpcRequestSchema, IpcResponseSchema, } from "./protocol/types.js";
+/**
+ * Unix domain socket server for MCP communication.
+ *
+ * Manages connections from GTKX applications and handles IPC messaging.
+ */
 export class SocketServer extends EventEmitter {
     server = null;
     connections = new Map();
@@ -61,7 +66,7 @@ export class SocketServer extends EventEmitter {
     }
     send(connectionId, message) {
         const connection = this.connections.get(connectionId);
-        if (!connection) {
+        if (!connection || !connection.socket.writable) {
             return false;
         }
         const data = `${JSON.stringify(message)}\n`;
@@ -111,15 +116,26 @@ export class SocketServer extends EventEmitter {
             this.send(connection.id, response);
             return;
         }
-        const result = IpcRequestSchema.safeParse(parsed);
-        if (!result.success) {
-            const response = {
-                id: parsed.id ?? "unknown",
-                error: invalidRequestError(result.error.message).toIpcError(),
-            };
-            this.send(connection.id, response);
-            return;
+        const message = parsed;
+        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;
+            }
         }
-        this.emit("request", connection, result.data);
+        const response = {
+            id: message.id ?? "unknown",
+            error: invalidRequestError("Invalid message format").toIpcError(),
+        };
+        this.send(connection.id, response);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/mcp",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "MCP server for AI-powered interaction with GTKX applications",
   "keywords": [
     "gtkx",
@@ -43,9 +43,8 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.24.0"
   },
-  "devDependencies": {},
   "scripts": {
-    "build": "tsc -b",
+    "build": "tsc -b && cp ../../README.md .",
     "test": "vitest run"
   }
 }