send_control_character

Instructions

Implementation Reference

• src/SendControlCharacter.ts:12-53 (handler)

  The `send()` method on the SendControlCharacter class executes the tool logic: it converts a letter to a control code (Ctrl+A=1, etc.), handles special cases for ']' (telnet escape, ASCII 29) and ESC (ASCII 27), then uses AppleScript via osascript to send the control character to iTerm2.

  async send(letter: string): Promise<void> {
    let controlCode: number;
    
    // Handle special cases for telnet escape sequences
    if (letter.toUpperCase() === ']') {
      // ASCII 29 (GS - Group Separator) - the telnet escape character
      controlCode = 29;
    } 
    // Add other special cases here as needed
    else if (letter.toUpperCase() === 'ESCAPE' || letter.toUpperCase() === 'ESC') {
      // ASCII 27 (ESC - Escape)
      controlCode = 27;
    }
    else {
      // Validate input for standard control characters
      letter = letter.toUpperCase();
      if (!/^[A-Z]$/.test(letter)) {
        throw new Error('Invalid control character letter');
      }
      
      // Convert to standard control code (A=1, B=2, etc.)
      controlCode = letter.charCodeAt(0) - 64;
    }
  
    // AppleScript to send the control character
    const ascript = `
      tell application "iTerm2"
        tell front window
          tell current session of current tab
            -- Send the control character
            write text (ASCII character ${controlCode})
          end tell
        end tell
      end tell
    `;
  
    try {
      await this.executeCommand(`osascript -e '${ascript}'`);
    } catch (error: unknown) {
      throw new Error(`Failed to send control character: ${(error as Error).message}`);
    }
  }

• src/index.ts:106-117 (handler)

  The CallToolRequestSchema handler case for 'send_control_character': instantiates SendControlCharacter, calls send() with the 'letter' argument, and returns a confirmation message.

  case "send_control_character": {
    const ttyControl = new SendControlCharacter();
    const letter = String(request.params.arguments?.letter);
    await ttyControl.send(letter);
    
    return {
      content: [{
        type: "text",
        text: `Sent control character: Control-${letter.toUpperCase()}`
      }]
    };
  }

• src/index.ts:57-69 (schema)

  Tool registration with input schema under ListToolsRequestSchema: defines the 'send_control_character' tool with required 'letter' (string) parameter, describing it as sending control characters (e.g., Control-C, telnet escape) to the active iTerm terminal.

    name: "send_control_character",
    description: "Sends a control character to the active iTerm terminal (e.g., Control-C, or special sequences like ']' for telnet escape)",
    inputSchema: {
      type: "object",
      properties: {
        letter: {
          type: "string",
          description: "The letter corresponding to the control character (e.g., 'C' for Control-C, ']' for telnet escape)"
        },
      },
      required: ["letter"]
    }
  }

• src/index.ts:11-11 (registration)

  Import statement registering the SendControlCharacter class from './SendControlCharacter.js'.

  import SendControlCharacter from "./SendControlCharacter.js";

• src/SendControlCharacter.ts:8-10 (helper)

  Helper method `executeCommand()` that wraps exec with promisify, used by send() to run the osascript command.

  protected async executeCommand(command: string): Promise<void> {
    await execPromise(command);
  }