@gtkx/mcp 0.21.0 → 1.0.0-rc.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gtkx/mcp",
-  "version": "0.21.0",
-  "description": "MCP server for AI-powered interaction with GTKX applications",
+  "version": "1.0.0-rc.2",
+  "description": "Model Context Protocol server that gives an agent the GTKX API reference and control of a running application",
   "keywords": [
     "gtkx",
     "gtk",
@@ -19,7 +19,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/gtkx-org/gtkx.git",
+    "url": "git+https://github.com/gtkx-org/gtkx.git",
     "directory": "packages/mcp"
   },
   "license": "MPL-2.0",
@@ -27,9 +27,9 @@
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
     }
   },
   "bin": {
@@ -41,13 +41,17 @@
     "dist",
     "src"
   ],
+  "engines": {
+    "node": ">=24"
+  },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.28.0",
-    "zod": "^4.3.6"
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.4.3",
+    "@gtkx/codegen": "1.0.0-rc.2",
+    "@gtkx/utils": "1.0.0-rc.2",
+    "@gtkx/config": "1.0.0-rc.2"
   },
   "scripts": {
-    "build": "tsc -b && cp ../../README.md .",
-    "test": "vitest run",
-    "typecheck": "tsc -b --emitDeclarationOnly"
+    "release": "tsx ../../scripts/release-package.ts"
   }
 }

package/src/app-router.ts

@@ -0,0 +1,209 @@
+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 ConnectionEvent,
+    type ConnectionRequestEvent,
+    type ProtocolConnection,
+} from "./transport.js";
+
+type AppRegisteredEvent = CustomEvent<AppInfo>;
+type AppUnregisteredEvent = CustomEvent<string>;
+
+type RegisteredApp = {
+    info: AppInfo;
+    connection: ProtocolConnection;
+};
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+
+function appRegisteredEvent(info: AppInfo): AppRegisteredEvent {
+    return new CustomEvent("appRegistered", { detail: info });
+}
+
+function appUnregisteredEvent(applicationId: string): AppUnregisteredEvent {
+    return new CustomEvent("appUnregistered", { detail: applicationId });
+}
+
+class AppRouter extends EventTarget {
+    private static defaultWaitTimeout = 10_000;
+
+    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.addEventListener("request", (event) => {
+            const { connection, request } = (event as ConnectionRequestEvent).detail;
+            this.handleRequest(connection, request);
+        });
+
+        this.connections.addEventListener("disconnection", (event) => {
+            this.removeApp((event as ConnectionEvent).detail);
+        });
+    }
+
+    private resolveTargetApp(applicationId: string | undefined): RegisteredApp {
+        const app = applicationId ? this.apps.get(applicationId) : this.getDefaultApp();
+
+        if (app) {
+            return app;
+        }
+
+        if (applicationId) {
+            throw appNotFoundError(applicationId);
+        }
+
+        throw noAppConnectedError();
+    }
+
+    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.dispatchEvent(appRegisteredEvent(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.dispatchEvent(appUnregisteredEvent(applicationId));
+    }
+
+    getApps(): AppInfo[] {
+        return this.apps.values().map((app) => app.info).toArray();
+    }
+
+    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.defaultWaitTimeout): Promise<AppInfo> {
+        const defaultApp = this.getDefaultApp();
+
+        if (defaultApp) {
+            return Promise.resolve(defaultApp.info);
+        }
+
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                this.removeEventListener("appRegistered", onRegister);
+
+                reject(
+                    new Error(
+                        `Timeout waiting for app registration after ${String(timeout)}ms. ` +
+                        "Make sure your GTKX app is running with 'gtkx dev'.",
+                    ),
+                );
+            }, timeout);
+
+            const onRegister = (event: Event): void => {
+                clearTimeout(timeoutId);
+                this.removeEventListener("appRegistered", onRegister);
+                resolve((event as AppRegisteredEvent).detail);
+            };
+
+            this.addEventListener("appRegistered", onRegister);
+        });
+    }
+
+    async sendToApp<T>(applicationId: string | undefined, method: string, params?: unknown): Promise<T> {
+        const app = this.resolveTargetApp(applicationId);
+
+        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;
+        }
+    }
+}
+
+export { AppRouter, appRegisteredEvent, appUnregisteredEvent, type AppRegisteredEvent, type AppUnregisteredEvent };

package/src/connection-registry.ts

@@ -0,0 +1,57 @@
+import type { Socket } from "node:net";
+import type { Message } from "./protocol/schemas.js";
+import {
+    type AppConnections,
+    connectionDisconnectionEvent,
+    connectionErrorEvent,
+    connectionRequestEvent,
+    ProtocolConnection,
+} from "./transport.js";
+
+class ConnectionRegistry extends EventTarget 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.dispatchEvent(connectionDisconnectionEvent(connection));
+            },
+            onError: (error) => this.dispatchEvent(connectionErrorEvent(error)),
+        });
+
+        this.connections.set(connection.id, connection);
+        this.sockets.set(connection.id, socket);
+        connection.on("request", (request) => this.dispatchEvent(connectionRequestEvent(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();
+        }
+    }
+}
+
+export { ConnectionRegistry };

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,128 +1,85 @@
-/**
- * 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,
-}
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 
-/**
- * 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;
+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;
 
-    constructor(code: McpErrorCode, message: string, data?: unknown) {
-        super(message);
-        this.code = code;
-        this.data = data;
-        this.name = "McpError";
+function isErrorCode(code: number): code is ErrorCode {
+    return (Object.values(ErrorCode) as number[]).includes(code);
+}
 
-        if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, McpError);
-        }
-    }
+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" },
+    );
+}
 
-    /**
-     * Converts the error to an IPC-compatible format.
-     *
-     * @returns Object suitable for IPC response error field
-     */
-    toIpcError(): { code: number; message: string; data?: unknown } {
-        return {
-            code: this.code,
-            message: this.message,
-            ...(this.data !== undefined && { data: this.data }),
-        };
-    }
+function appNotFoundError(applicationId: string): ProtocolError {
+    return new ProtocolError(ErrorCode.APP_NOT_FOUND, `Application '${applicationId}' not found`, { applicationId });
 }
 
-/**
- * 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" },
+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 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 });
+function widgetNotFoundError(widgetId: string): ProtocolError {
+    return new ProtocolError(ErrorCode.WIDGET_NOT_FOUND, `Widget '${widgetId}' not found`, { widgetId });
 }
 
-/**
- * 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 });
+function requestTimeoutError(timeout: number): ProtocolError {
+    return new ProtocolError(ErrorCode.REQUEST_TIMEOUT, `Request timed out after ${String(timeout)}ms`, { timeout });
 }
 
-/**
- * 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 });
+function invalidRequestError(reason: string): ProtocolError {
+    return new ProtocolError(ErrorCode.INVALID_REQUEST, `Invalid request: ${reason}`, { reason });
 }
 
-/**
- * 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 });
+function methodNotFoundError(method: string): ProtocolError {
+    return new ProtocolError(ErrorCode.METHOD_NOT_FOUND, `Method '${method}' not found`, { method });
 }
 
-/**
- * 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 });
+class ProtocolError extends Error {
+    code: ErrorCode;
+    data?: unknown;
+
+    constructor(code: ErrorCode, message: string, data?: unknown) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = "ProtocolError";
+    }
+
+    toErrorObject(): { code: number; message: string; data?: unknown } {
+        return {
+            code: this.code,
+            message: this.message,
+            ...(this.data !== undefined && { data: this.data }),
+        };
+    }
 }
+
+export {
+    ErrorCode,
+    isErrorCode,
+    noAppConnectedError,
+    appNotFoundError,
+    connectionWriteFailedError,
+    widgetNotFoundError,
+    requestTimeoutError,
+    invalidRequestError,
+    methodNotFoundError,
+    ProtocolError,
+};