send_control_character

Send control characters (e.g., Control-C or telnet escape) to the active iTerm terminal for managing processes or executing commands directly within the terminal session.

Instructions

Sends a control character to the active iTerm terminal (e.g., Control-C, or special sequences like ']' for telnet escape)

Input Schema

TableJSON Schema

Name	Required	Description	Default
`letter`	Yes	The letter corresponding to the control character (e.g., 'C' for Control-C, ']' for telnet escape)

Implementation Reference

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

Core implementation of the send_control_character tool: maps input letter to control code (with special cases for ']' and 'ESC'), constructs iTerm2 AppleScript, and executes it using osascript to send the character.

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:59-68 (schema)

Input schema for the tool, defining 'letter' as required string parameter.

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:57-69 (registration)

Registration of the tool in the MCP server's ListTools response, including name, description, and input schema.

  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:106-117 (handler)

MCP CallTool request handler dispatch for send_control_character: instantiates the class and calls send() with the letter argument, returns 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()}`
    }]
  };
}

iTerm MCP Server