@gtkx/mcp 0.20.0 → 1.0.0-rc.1

package/src/app-router.ts

@@ -0,0 +1,172 @@
+import EventEmitter from "node:events";
+import {
+    appNotFoundError,
+    connectionWriteFailedError,
+    invalidRequestError,
+    methodNotFoundError,
+    noAppConnectedError,
+    type ProtocolError,
+} from "./protocol/errors.js";
+import { type AppInfo, RegisterParamsSchema, type Request, type Response } from "./protocol/schemas.js";
+import { type AppConnections, ConnectionClosedError, type ProtocolConnection } from "./transport.js";
+
+type AppRouterEventMap = {
+    appRegistered: [AppInfo];
+    appUnregistered: [string];
+};
+
+type RegisteredApp = {
+    info: AppInfo;
+    connection: ProtocolConnection;
+};
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+
+export class AppRouter extends EventEmitter<AppRouterEventMap> {
+    private static DEFAULT_WAIT_TIMEOUT = 10000;
+
+    private apps: Map<string, RegisteredApp> = new Map();
+    private connectionToApp: Map<string, string> = new Map();
+    private requestTimeout: number;
+    private connections: AppConnections;
+
+    constructor(connections: AppConnections, options: { requestTimeout?: number } = {}) {
+        super();
+        this.connections = connections;
+        this.requestTimeout = options.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT_MS;
+
+        this.connections.on("request", (connection, request) => {
+            this.handleRequest(connection, request);
+        });
+
+        this.connections.on("disconnection", (connection) => {
+            this.removeApp(connection);
+        });
+    }
+
+    getApps(): AppInfo[] {
+        return Array.from(this.apps.values()).map((app) => app.info);
+    }
+
+    hasConnectedApps(): boolean {
+        return this.apps.size > 0;
+    }
+
+    getDefaultApp(): RegisteredApp | undefined {
+        const first = this.apps.values().next();
+        return first.done ? undefined : first.value;
+    }
+
+    getProjectRoot(): string | undefined {
+        return this.getDefaultApp()?.info.projectRoot;
+    }
+
+    waitForApp(timeout: number = AppRouter.DEFAULT_WAIT_TIMEOUT): Promise<AppInfo> {
+        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: AppInfo) => {
+                clearTimeout(timeoutId);
+                this.off("appRegistered", onRegister);
+                resolve(appInfo);
+            };
+
+            this.on("appRegistered", onRegister);
+        });
+    }
+
+    async sendToApp<T>(applicationId: string | undefined, method: string, params?: unknown): Promise<T> {
+        const app = applicationId ? this.apps.get(applicationId) : this.getDefaultApp();
+
+        if (!app) {
+            if (applicationId) {
+                throw appNotFoundError(applicationId);
+            }
+            throw noAppConnectedError();
+        }
+
+        try {
+            return await app.connection.send<T>(method, params, this.requestTimeout);
+        } catch (error) {
+            if (error instanceof ConnectionClosedError) {
+                this.removeApp(app.connection);
+                throw connectionWriteFailedError(app.info.applicationId);
+            }
+            throw error;
+        }
+    }
+
+    private handleRequest(connection: ProtocolConnection, request: Request): void {
+        if (request.method === "app.register") {
+            this.handleRegister(connection, request);
+        } else if (request.method === "app.unregister") {
+            this.handleUnregister(connection, request);
+        } else {
+            this.sendError(connection, request, methodNotFoundError(request.method));
+        }
+    }
+
+    private handleRegister(connection: ProtocolConnection, request: Request): void {
+        const parseResult = RegisterParamsSchema.safeParse(request.params);
+        if (!parseResult.success) {
+            this.sendError(connection, request, invalidRequestError(parseResult.error.message));
+            return;
+        }
+
+        const params = parseResult.data;
+        const appInfo: AppInfo = {
+            applicationId: params.applicationId,
+            pid: params.pid,
+            ...(params.projectRoot === undefined ? {} : { projectRoot: params.projectRoot }),
+        };
+
+        this.apps.set(params.applicationId, { info: appInfo, connection });
+        this.connectionToApp.set(connection.id, params.applicationId);
+
+        this.acknowledge(connection, request);
+
+        this.emit("appRegistered", appInfo);
+    }
+
+    private handleUnregister(connection: ProtocolConnection, request: Request): void {
+        this.removeApp(connection);
+        this.acknowledge(connection, request);
+    }
+
+    private acknowledge(connection: ProtocolConnection, request: Request): void {
+        const response: Response = {
+            id: request.id,
+            result: { success: true },
+        };
+        this.connections.send(connection.id, response);
+    }
+
+    private sendError(connection: ProtocolConnection, request: Request, error: ProtocolError): void {
+        this.connections.send(connection.id, {
+            id: request.id,
+            error: error.toErrorObject(),
+        });
+    }
+
+    private removeApp(connection: ProtocolConnection): void {
+        const applicationId = this.connectionToApp.get(connection.id);
+        this.connectionToApp.delete(connection.id);
+        if (applicationId === undefined) return;
+        if (this.apps.get(applicationId)?.connection !== connection) return;
+        this.apps.delete(applicationId);
+        this.emit("appUnregistered", applicationId);
+    }
+}

package/src/connection-registry.ts

@@ -0,0 +1,42 @@
+import EventEmitter from "node:events";
+import type { Socket } from "node:net";
+import type { Message } from "./protocol/schemas.js";
+import { type AppConnectionEvents, type AppConnections, ProtocolConnection } from "./transport.js";
+
+export class ConnectionRegistry extends EventEmitter<AppConnectionEvents> implements AppConnections {
+    private connections: Map<string, ProtocolConnection> = new Map();
+    private sockets: Map<string, Socket> = new Map();
+
+    register(socket: Socket): ProtocolConnection {
+        const connection = ProtocolConnection.fromSocket(socket, {
+            onClose: () => {
+                this.connections.delete(connection.id);
+                this.sockets.delete(connection.id);
+                this.emit("disconnection", connection);
+            },
+            onError: (error) => this.emit("error", error),
+        });
+        this.connections.set(connection.id, connection);
+        this.sockets.set(connection.id, socket);
+        connection.on("request", (request) => this.emit("request", connection, request));
+        connection.on("invalid", ({ id: badId, error }) => {
+            connection.write({ id: badId, error: error.toErrorObject() });
+        });
+        return connection;
+    }
+
+    send(connectionId: string, message: Message): void {
+        const connection = this.connections.get(connectionId);
+        if (!connection) return;
+        connection.write(message);
+    }
+
+    dispose(reason: string): void {
+        for (const connection of this.connections.values()) {
+            connection.rejectPending(new Error(reason));
+        }
+        for (const socket of this.sockets.values()) {
+            socket.destroy();
+        }
+    }
+}

package/src/internal.ts

@@ -0,0 +1,17 @@
+export {
+    ErrorCode,
+    invalidRequestError,
+    methodNotFoundError,
+    ProtocolError,
+    widgetNotFoundError,
+} from "./protocol/errors.js";
+export {
+    DEFAULT_SOCKET_PATH,
+    type ParamsSchema,
+    type Request,
+    type SerializedWidget,
+    type ServerInitiatedMethod,
+    type ServerRequestParams,
+    ServerRequestParamsSchemas,
+} from "./protocol/schemas.js";
+export { ProtocolConnection } from "./transport.js";

package/src/protocol/errors.ts

@@ -1,61 +1,32 @@
-/**
- * Error codes for MCP protocol errors.
- */
-export 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,
+export const ErrorCode = {
+    INTERNAL_ERROR: 1000,
+    NO_APP_CONNECTED: 1001,
+    APP_NOT_FOUND: 1002,
+    WIDGET_NOT_FOUND: 1003,
+    CONNECTION_WRITE_FAILED: 1004,
+    REQUEST_TIMEOUT: 1005,
+    INVALID_REQUEST: 1006,
+    METHOD_NOT_FOUND: 1007,
+} as const;
+
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+export function isErrorCode(code: number): code is ErrorCode {
+    return (Object.values(ErrorCode) as number[]).includes(code);
 }
 
-/**
- * Error class for MCP protocol errors.
- *
- * Contains an error code, message, and optional additional data.
- */
-export class McpError extends Error {
-    /** The MCP error code */
-    readonly code: McpErrorCode;
-    /** Additional error context */
-    readonly data?: unknown;
+export class ProtocolError extends Error {
+    code: ErrorCode;
+    data?: unknown;
 
-    constructor(code: McpErrorCode, message: string, data?: unknown) {
+    constructor(code: ErrorCode, message: string, data?: unknown) {
         super(message);
         this.code = code;
         this.data = data;
-        this.name = "McpError";
-
-        if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, McpError);
-        }
+        this.name = "ProtocolError";
     }
 
-    /**
-     * Converts the error to an IPC-compatible format.
-     *
-     * @returns Object suitable for IPC response error field
-     */
-    toIpcError(): { code: number; message: string; data?: unknown } {
+    toErrorObject(): { code: number; message: string; data?: unknown } {
         return {
             code: this.code,
             message: this.message,
@@ -64,65 +35,38 @@ 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(): McpError {
-    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" },
+export function noAppConnectedError(): ProtocolError {
+    return new ProtocolError(
+        ErrorCode.NO_APP_CONNECTED,
+        "No GTKX application connected: start an app with 'gtkx dev' to connect",
+        { hint: "Run 'gtkx dev' 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: string): McpError {
-    return new McpError(McpErrorCode.APP_NOT_FOUND, `Application '${appId}' not found`, { appId });
+export function appNotFoundError(applicationId: string): ProtocolError {
+    return new ProtocolError(ErrorCode.APP_NOT_FOUND, `Application '${applicationId}' not found`, { applicationId });
+}
+
+export function connectionWriteFailedError(applicationId: string): ProtocolError {
+    return new ProtocolError(
+        ErrorCode.CONNECTION_WRITE_FAILED,
+        `Connection to application '${applicationId}' is no longer writable`,
+        { applicationId },
+    );
 }
 
-/**
- * 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: string): McpError {
-    return new McpError(McpErrorCode.WIDGET_NOT_FOUND, `Widget '${widgetId}' not found`, { widgetId });
+export function widgetNotFoundError(widgetId: string): ProtocolError {
+    return new ProtocolError(ErrorCode.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: number): McpError {
-    return new McpError(McpErrorCode.IPC_TIMEOUT, `IPC request timed out after ${timeout}ms`, { timeout });
+export function requestTimeoutError(timeout: number): ProtocolError {
+    return new ProtocolError(ErrorCode.REQUEST_TIMEOUT, `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: string): McpError {
-    return new McpError(McpErrorCode.INVALID_REQUEST, `Invalid request: ${reason}`, { reason });
+export function invalidRequestError(reason: string): ProtocolError {
+    return new ProtocolError(ErrorCode.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: string): McpError {
-    return new McpError(McpErrorCode.METHOD_NOT_FOUND, `Method '${method}' not found`, { method });
+export function methodNotFoundError(method: string): ProtocolError {
+    return new ProtocolError(ErrorCode.METHOD_NOT_FOUND, `Method '${method}' not found`, { method });
 }

package/src/protocol/schemas.ts

@@ -0,0 +1,148 @@
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+
+export const RequestSchema: z.ZodObject<
+    {
+        id: z.ZodString;
+        method: z.ZodString;
+        params: z.ZodOptional<z.ZodUnknown>;
+    },
+    z.core.$strip
+> = z.object({
+    id: z.string(),
+    method: z.string(),
+    params: z.unknown().optional(),
+});
+
+export type Request = z.infer<typeof RequestSchema>;
+
+const ErrorSchema: z.ZodObject<
+    { code: z.ZodNumber; message: z.ZodString; data: z.ZodOptional<z.ZodUnknown> },
+    z.core.$strip
+> = z.object({
+    code: z.number(),
+    message: z.string(),
+    data: z.unknown().optional(),
+});
+
+export const ResponseSchema: z.ZodObject<
+    {
+        id: z.ZodString;
+        result: z.ZodOptional<z.ZodUnknown>;
+        error: z.ZodOptional<typeof ErrorSchema>;
+    },
+    z.core.$strip
+> = z.object({
+    id: z.string(),
+    result: z.unknown().optional(),
+    error: ErrorSchema.optional(),
+});
+
+export type Response = z.infer<typeof ResponseSchema>;
+
+export type SerializedWidget = {
+    id: string;
+    type: string;
+    role: string;
+    name: string | null;
+    text: string | null;
+    sensitive: boolean;
+    visible: boolean;
+    cssClasses: string[];
+    children: SerializedWidget[];
+};
+
+export type AppInfo = {
+    applicationId: string;
+    pid: number;
+    projectRoot?: string;
+};
+
+export const RegisterParamsSchema: z.ZodObject<
+    {
+        applicationId: z.ZodString;
+        pid: z.ZodNumber;
+        projectRoot: z.ZodOptional<z.ZodString>;
+    },
+    z.core.$strip
+> = z.object({
+    applicationId: z.string(),
+    pid: z.number(),
+    projectRoot: z.string().optional(),
+});
+
+const emptyParams: z.ZodObject<Record<string, never>, z.core.$strip> = z.object({});
+export const widgetIdParams: z.ZodObject<{ widgetId: z.ZodString }, z.core.$strip> = z.object({
+    widgetId: z.string(),
+});
+export const queryOptionsSchema: z.ZodObject<
+    { name: z.ZodOptional<z.ZodString>; exact: z.ZodOptional<z.ZodBoolean>; timeout: z.ZodOptional<z.ZodNumber> },
+    z.core.$strip
+> = z.object({
+    name: z.string().optional(),
+    exact: z.boolean().optional(),
+    timeout: z.number().optional(),
+});
+
+export const queryParams: z.ZodObject<
+    {
+        by: z.ZodEnum<{ role: "role"; text: "text"; name: "name"; labelText: "labelText" }>;
+        value: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+        options: z.ZodOptional<typeof queryOptionsSchema>;
+    },
+    z.core.$strip
+> = z.object({
+    by: z.enum(["role", "text", "name", "labelText"]),
+    value: z.union([z.string(), z.number()]),
+    options: queryOptionsSchema.optional(),
+});
+export const typeParams: z.ZodObject<
+    { widgetId: z.ZodString; text: z.ZodString; clear: z.ZodOptional<z.ZodBoolean> },
+    z.core.$strip
+> = z.object({ widgetId: z.string(), text: z.string(), clear: z.boolean().optional() });
+export const fireEventParams: z.ZodObject<
+    { widgetId: z.ZodString; signal: z.ZodString; args: z.ZodOptional<z.ZodArray<z.ZodUnknown>> },
+    z.core.$strip
+> = z.object({ widgetId: z.string(), signal: z.string(), args: z.array(z.unknown()).optional() });
+export const screenshotParams: z.ZodObject<
+    { windowId: z.ZodOptional<z.ZodString>; path: z.ZodOptional<z.ZodString> },
+    z.core.$strip
+> = z.object({
+    windowId: z.string().optional(),
+    path: z.string().optional(),
+});
+
+export const ServerRequestParamsSchemas: {
+    "app.getWindows": typeof emptyParams;
+    "widget.getTree": typeof emptyParams;
+    "widget.query": typeof queryParams;
+    "widget.getProps": typeof widgetIdParams;
+    "widget.click": typeof widgetIdParams;
+    "widget.type": typeof typeParams;
+    "widget.fireEvent": typeof fireEventParams;
+    "widget.screenshot": typeof screenshotParams;
+} = {
+    "app.getWindows": emptyParams,
+    "widget.getTree": emptyParams,
+    "widget.query": queryParams,
+    "widget.getProps": widgetIdParams,
+    "widget.click": widgetIdParams,
+    "widget.type": typeParams,
+    "widget.fireEvent": fireEventParams,
+    "widget.screenshot": screenshotParams,
+};
+
+export type ServerRequestParams<Method extends keyof typeof ServerRequestParamsSchemas> = z.infer<
+    (typeof ServerRequestParamsSchemas)[Method]
+>;
+
+export type ParamsSchema<Output> = z.ZodType<Output>;
+
+export type ServerInitiatedMethod = keyof typeof ServerRequestParamsSchemas;
+
+export type Message = Request | Response;
+
+const getRuntimeDir = (): string => process.env.XDG_RUNTIME_DIR ?? tmpdir();
+
+export const DEFAULT_SOCKET_PATH: string = join(getRuntimeDir(), "gtkx-mcp.sock");