CNCjs MCP Server

Instructions

Implementation Reference

• src/tools/connection.ts:17-42 (handler)

  Main tool registration and handler for connect_to_port. Validates input parameters, auto-connects to CNCjs server if needed, checks if a port is already connected, and calls client.openPort() to establish the serial connection.

  server.tool(
    "connect_to_port",
    "Open a serial connection to a CNC controller",
    {
      port: z.string().describe("Serial port path (e.g., /dev/cu.usbmodem14201)"),
      baudrate: z.number().default(115200).describe("Baud rate (default 115200)"),
      controllerType: z.string().default("Grbl").describe("Controller type (default Grbl)"),
    },
    async ({ port, baudrate, controllerType }) => {
      try {
        // Auto-connect to CNCjs server if not already connected
        if (!client.isConnectedToServer) {
          await client.connectToServer();
        }
  
        if (client.connectedPort) {
          return err(`Already connected to port ${client.connectedPort}. Disconnect first.`);
        }
  
        await client.openPort(port, baudrate, controllerType);
        return text(`Connected to ${port} at ${baudrate} baud (${controllerType} controller).`);
      } catch (e: any) {
        return err(e.message);
      }
    }
  );

• src/tools/connection.ts:20-24 (schema)

  Input schema validation for connect_to_port tool. Defines three parameters: port (string, required), baudrate (number, default 115200), and controllerType (string, default 'Grbl').

  {
    port: z.string().describe("Serial port path (e.g., /dev/cu.usbmodem14201)"),
    baudrate: z.number().default(115200).describe("Baud rate (default 115200)"),
    controllerType: z.string().default("Grbl").describe("Controller type (default Grbl)"),
  },

• src/cncjs-client.ts:321-350 (helper)

  openPort helper method that performs the actual serial port connection. Emits 'open' event to CNCjs socket, waits for 'serialport:open' success or 'serialport:error' failure, and manages connection state.

  async openPort(
    port: string,
    baudrate: number = 115200,
    controllerType: string = "Grbl"
  ): Promise<void> {
    this.ensureConnected();
    return new Promise((resolve, reject) => {
      const timeout = setTimeout(() => reject(new Error("Open port timeout")), 10000);
  
      // Listen for success or error
      const onOpen = () => {
        clearTimeout(timeout);
        cleanup();
        resolve();
      };
      const onError = (data: any) => {
        clearTimeout(timeout);
        cleanup();
        reject(new Error(`Failed to open port: ${JSON.stringify(data)}`));
      };
      const cleanup = () => {
        this.socket!.removeListener("serialport:open", onOpen);
        this.socket!.removeListener("serialport:error", onError);
      };
  
      this.socket!.on("serialport:open", onOpen);
      this.socket!.on("serialport:error", onError);
      this.socket!.emit("open", port, { controllerType, baudrate });
    });
  }

• src/cncjs-client.ts:108-142 (helper)

  connectToServer helper method called by the connect_to_port handler when not already connected to CNCjs. Establishes Socket.IO connection to the CNCjs server and sets up event listeners.

  async connectToServer(): Promise<void> {
    if (this.socket && this._connected) return;
  
    return new Promise((resolve, reject) => {
      const opts: Record<string, any> = {
        query: this.config.token ? `token=${this.config.token}` : "",
      };
  
      this.socket = io(this.config.url, opts);
  
      const timeout = setTimeout(() => {
        reject(new Error(`Connection timeout to CNCjs at ${this.config.url}`));
      }, 10000);
  
      this.socket.on("connect", () => {
        clearTimeout(timeout);
        this._connected = true;
        console.error(`[cncjs-mcp] Connected to CNCjs at ${this.config.url}`);
        this.setupListeners();
        resolve();
      });
  
      this.socket.on("connect_error", (err: Error) => {
        clearTimeout(timeout);
        this._connected = false;
        reject(new Error(`Failed to connect to CNCjs: ${err.message}`));
      });
  
      this.socket.on("disconnect", () => {
        this._connected = false;
        this._connectedPort = null;
        console.error("[cncjs-mcp] Disconnected from CNCjs");
      });
    });
  }

• src/types.ts:61-65 (schema)

  SerialPort interface type definition used for port listing and connection operations. Defines the structure of serial port data with port, manufacturer, and inuse properties.

  export interface SerialPort {
    port: string;
    manufacturer?: string;
    inuse?: boolean;
  }