@gtkx/mcp 0.20.0 → 1.0.0-rc.1

package/src/socket-server.ts

@@ -1,99 +1,61 @@
-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,
-    type IpcMessage,
-    type IpcRequest,
-    IpcRequestSchema,
-    type IpcResponse,
-    IpcResponseSchema,
-} from "./protocol/types.js";
-
-type SocketServerEventMap = {
-    connection: [AppConnection];
-    disconnection: [AppConnection];
-    request: [AppConnection, IpcRequest];
-    response: [AppConnection, IpcResponse];
-    error: [Error];
-};
-
-/**
- * Represents a connected application.
- */
-export type AppConnection = {
-    /** Unique connection identifier */
-    id: string;
-    /** The underlying socket */
-    socket: net.Socket;
-    /** Buffer for incomplete messages */
-    buffer: string;
-};
+import type { ConnectionRegistry } from "./connection-registry.js";
+import { DEFAULT_SOCKET_PATH } from "./protocol/schemas.js";
+
+const isSocketLive = (socketPath: string): Promise<boolean> =>
+    new Promise((resolve) => {
+        const probe = net.connect(socketPath);
+        probe.once("connect", () => {
+            probe.destroy();
+            resolve(true);
+        });
+        probe.once("error", () => resolve(false));
+    });
 
-/**
- * Unix domain socket server for MCP communication.
- *
- * Manages connections from GTKX applications and handles IPC messaging.
- */
-export class SocketServer extends EventEmitter<SocketServerEventMap> {
+export class SocketServer {
     private server: net.Server | null = null;
-    private connections: Map<string, AppConnection> = new Map();
     private socketPath: string;
+    private registry: ConnectionRegistry;
 
-    constructor(socketPath: string = DEFAULT_SOCKET_PATH) {
-        super();
+    constructor(registry: ConnectionRegistry, socketPath: string = DEFAULT_SOCKET_PATH) {
+        this.registry = registry;
         this.socketPath = socketPath;
     }
 
-    get path(): string {
-        return this.socketPath;
-    }
-
-    get isListening(): boolean {
-        return this.server?.listening ?? false;
-    }
-
-    getConnections(): AppConnection[] {
-        return Array.from(this.connections.values());
-    }
-
-    getConnection(id: string): AppConnection | undefined {
-        return this.connections.get(id);
-    }
-
     async start(): Promise<void> {
-        if (this.server) {
-            return;
-        }
+        if (this.server) return;
 
         if (fs.existsSync(this.socketPath)) {
+            if (await isSocketLive(this.socketPath)) {
+                throw new Error(
+                    `Another GTKX MCP server already owns ${this.socketPath}. ` +
+                        "Stop the other server (for example, the gtkx MCP server of another active session) and reconnect.",
+                );
+            }
             fs.unlinkSync(this.socketPath);
         }
 
         return new Promise((resolve, reject) => {
-            this.server = net.createServer((socket) => this.handleConnection(socket));
+            this.server = net.createServer((socket) => this.registry.register(socket));
 
+            let listening = false;
             this.server.on("error", (error) => {
-                this.emit("error", error);
-                reject(error);
+                this.registry.emit("error", error);
+                if (!listening) reject(error);
             });
 
             this.server.listen(this.socketPath, () => {
+                listening = true;
                 resolve();
             });
         });
     }
 
     async stop(): Promise<void> {
-        if (!this.server) {
-            return;
-        }
+        if (!this.server) return;
 
-        for (const connection of this.connections.values()) {
-            connection.socket.destroy();
-        }
-        this.connections.clear();
+        this.registry.dispose("Server stopping");
 
         return new Promise((resolve) => {
             this.server?.close(() => {
@@ -105,90 +67,4 @@ export class SocketServer extends EventEmitter<SocketServerEventMap> {
             });
         });
     }
-
-    send(connectionId: string, message: IpcMessage): boolean {
-        const connection = this.connections.get(connectionId);
-        if (!connection || !connection.socket.writable) {
-            return false;
-        }
-
-        const data = `${JSON.stringify(message)}\n`;
-        connection.socket.write(data);
-        return true;
-    }
-
-    private handleConnection(socket: net.Socket): void {
-        const connectionId = crypto.randomUUID();
-        const connection: AppConnection = {
-            id: connectionId,
-            socket,
-            buffer: "",
-        };
-
-        this.connections.set(connectionId, connection);
-        this.emit("connection", connection);
-
-        socket.on("data", (data: Buffer) => this.handleData(connection, data));
-
-        socket.on("close", () => {
-            this.connections.delete(connectionId);
-            this.emit("disconnection", connection);
-        });
-
-        socket.on("error", (error) => {
-            this.emit("error", error);
-        });
-    }
-
-    private handleData(connection: AppConnection, data: Buffer): void {
-        connection.buffer += data.toString();
-
-        let newlineIndex = connection.buffer.indexOf("\n");
-        while (newlineIndex !== -1) {
-            const line = connection.buffer.slice(0, newlineIndex);
-            connection.buffer = connection.buffer.slice(newlineIndex + 1);
-
-            if (line.trim()) {
-                this.processMessage(connection, line);
-            }
-            newlineIndex = connection.buffer.indexOf("\n");
-        }
-    }
-
-    private processMessage(connection: AppConnection, line: string): void {
-        let parsed: unknown;
-        try {
-            parsed = JSON.parse(line);
-        } catch {
-            const response: IpcResponse = {
-                id: "unknown",
-                error: invalidRequestError("Invalid JSON").toIpcError(),
-            };
-            this.send(connection.id, response);
-            return;
-        }
-
-        const message = parsed as Record<string, unknown>;
-        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;
-            }
-        }
-
-        const response: IpcResponse = {
-            id: (message.id as string | undefined) ?? "unknown",
-            error: invalidRequestError("Invalid message format").toIpcError(),
-        };
-        this.send(connection.id, response);
-    }
 }

package/src/tool.ts

@@ -0,0 +1,66 @@
+import type { McpServer, ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { z } from "zod";
+import { ProtocolError } from "./protocol/errors.js";
+
+export const textContent = (text: string): CallToolResult => ({ content: [{ type: "text", text }] });
+
+export const textError = (text: string): CallToolResult => ({
+    content: [{ type: "text", text }],
+    isError: true,
+});
+
+export const imageContent = (data: string, mimeType: string): CallToolResult => ({
+    content: [{ type: "image", data, mimeType }],
+});
+
+export type ToolArgs<Shape extends Record<string, z.ZodType>> = { [K in keyof Shape]: z.output<Shape[K]> };
+
+type ToolKind = "readOnly" | "action";
+
+export type Tool<Shape extends Record<string, z.ZodType> = Record<string, z.ZodType>> = {
+    name: string;
+    title: string;
+    kind: ToolKind;
+    description: string;
+    inputSchema: Shape;
+    handler: (args: ToolArgs<Shape>) => Promise<CallToolResult>;
+};
+
+const hasStringHint = (data: unknown): data is { hint: string } =>
+    typeof data === "object" && data !== null && "hint" in data && typeof data.hint === "string";
+
+const runTool = async (
+    handler: (args: ToolArgs<Record<string, z.ZodType>>) => Promise<CallToolResult>,
+    args: ToolArgs<Record<string, z.ZodType>>,
+): Promise<CallToolResult> => {
+    try {
+        return await handler(args);
+    } catch (error) {
+        if (error instanceof ProtocolError) {
+            return textError(hasStringHint(error.data) ? `${error.message}\n${error.data.hint}` : error.message);
+        }
+        return textError(error instanceof Error ? error.message : String(error));
+    }
+};
+
+export const defineTool = <Shape extends Record<string, z.ZodType>>(tool: Tool<Shape>): Tool => tool as Tool;
+
+export const registerTool = (server: McpServer, tool: Tool): void => {
+    const callback = ((args: ToolArgs<Record<string, z.ZodType>>, _extra: unknown) =>
+        runTool(tool.handler, args)) as ToolCallback<Record<string, z.ZodType>>;
+    server.registerTool(
+        tool.name,
+        {
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: {
+                title: tool.title,
+                readOnlyHint: tool.kind === "readOnly",
+                destructiveHint: tool.kind === "action",
+                openWorldHint: true,
+            },
+        },
+        callback,
+    );
+};

package/src/transport.ts

@@ -0,0 +1,165 @@
+import EventEmitter from "node:events";
+import type { Socket } from "node:net";
+import type { Duplex } from "node:stream";
+import { ErrorCode, invalidRequestError, isErrorCode, ProtocolError, requestTimeoutError } from "./protocol/errors.js";
+import { type Message, type Request, RequestSchema, type Response, ResponseSchema } from "./protocol/schemas.js";
+
+export type ProtocolConnectionEvents = {
+    request: [Request];
+    invalid: [{ id: string; error: ProtocolError }];
+};
+
+type PendingRequest = {
+    resolve: (result: unknown) => void;
+    reject: (error: Error) => void;
+    timeout: NodeJS.Timeout;
+};
+
+export class ConnectionClosedError extends Error {
+    constructor() {
+        super("Connection stream is not writable");
+        this.name = "ConnectionClosedError";
+    }
+}
+
+export class ProtocolConnection extends EventEmitter<ProtocolConnectionEvents> {
+    id: string = crypto.randomUUID();
+    private buffer = "";
+    private pending: Map<string, PendingRequest> = new Map();
+    private writer: Duplex;
+
+    constructor(writer: Duplex) {
+        super();
+        this.writer = writer;
+    }
+
+    feed(data: Buffer | string): void {
+        this.buffer += typeof data === "string" ? data : data.toString();
+
+        let newlineIndex = this.buffer.indexOf("\n");
+        while (newlineIndex !== -1) {
+            const line = this.buffer.slice(0, newlineIndex);
+            this.buffer = this.buffer.slice(newlineIndex + 1);
+
+            if (line.trim()) {
+                this.processLine(line);
+            }
+            newlineIndex = this.buffer.indexOf("\n");
+        }
+    }
+
+    write(message: Message): void {
+        if (!this.writer.writable) return;
+        this.writer.write(`${JSON.stringify(message)}\n`);
+    }
+
+    static fromSocket(
+        socket: Socket,
+        options: {
+            onClose?: () => void;
+            onError?: (error: Error) => void;
+        } = {},
+    ): ProtocolConnection {
+        const connection = new ProtocolConnection(socket);
+        socket.on("data", (data: Buffer) => connection.feed(data));
+        socket.on("close", () => {
+            connection.rejectPending(new Error("Connection closed"));
+            options.onClose?.();
+        });
+        if (options.onError) {
+            socket.on("error", options.onError);
+        }
+        return connection;
+    }
+
+    send<T = unknown>(method: string, params: unknown, timeout: number): Promise<T> {
+        return new Promise<T>((resolve, reject) => {
+            if (!this.writer.writable) {
+                reject(new ConnectionClosedError());
+                return;
+            }
+
+            const id = crypto.randomUUID();
+            const timeoutHandle = setTimeout(() => {
+                this.pending.delete(id);
+                reject(requestTimeoutError(timeout));
+            }, timeout);
+
+            this.pending.set(id, {
+                resolve: resolve as (result: unknown) => void,
+                reject,
+                timeout: timeoutHandle,
+            });
+
+            this.write({ id, method, params });
+            if (!this.writer.writable) {
+                clearTimeout(timeoutHandle);
+                this.pending.delete(id);
+                reject(new ConnectionClosedError());
+            }
+        });
+    }
+
+    rejectPending(error: Error): void {
+        for (const entry of this.pending.values()) {
+            clearTimeout(entry.timeout);
+            entry.reject(error);
+        }
+        this.pending.clear();
+    }
+
+    private processLine(line: string): void {
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(line);
+        } catch {
+            this.emit("invalid", { id: "unknown", error: invalidRequestError("Invalid JSON") });
+            return;
+        }
+
+        const message = parsed as Record<string, unknown>;
+        if (typeof message.method === "string") {
+            const requestResult = RequestSchema.safeParse(parsed);
+            if (requestResult.success) {
+                this.emit("request", requestResult.data);
+                return;
+            }
+        } else {
+            const responseResult = ResponseSchema.safeParse(parsed);
+            if (responseResult.success) {
+                this.handleResponse(responseResult.data);
+                return;
+            }
+        }
+
+        const id = typeof message.id === "string" ? message.id : "unknown";
+        this.emit("invalid", { id, error: invalidRequestError("Invalid message format") });
+    }
+
+    private handleResponse(response: Response): void {
+        const entry = this.pending.get(response.id);
+        if (!entry) return;
+
+        clearTimeout(entry.timeout);
+        this.pending.delete(response.id);
+
+        if (response.error) {
+            const err = response.error;
+            entry.reject(
+                new ProtocolError(isErrorCode(err.code) ? err.code : ErrorCode.INTERNAL_ERROR, err.message, err.data),
+            );
+        } else {
+            entry.resolve(response.result);
+        }
+    }
+}
+
+export type AppConnectionEvents = {
+    disconnection: [ProtocolConnection];
+    request: [ProtocolConnection, Request];
+    error: [Error];
+};
+
+export interface AppConnections extends EventEmitter<AppConnectionEvents> {
+    send(connectionId: string, message: Message): void;
+}

package/dist/cli.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}