read_terminal_output

Instructions

Implementation Reference

• src/index.ts:95-105 (handler)

  MCP server handler for the 'read_terminal_output' tool. Extracts 'linesOfOutput' from arguments (default 25), calls TtyOutputReader.call(), and returns the output as text content.

  case "read_terminal_output": {
    const linesOfOutput = Number(request.params.arguments?.linesOfOutput) || 25
    const output = await TtyOutputReader.call(linesOfOutput)
  
    return {
      content: [{
        type: "text",
        text: output
      }]
    };
  }

• src/index.ts:43-54 (schema)

  Schema definition for the 'read_terminal_output' tool, specifying input as object with required 'linesOfOutput' number.

  name: "read_terminal_output",
  description: "Reads the output from the active iTerm terminal",
  inputSchema: {
    type: "object",
    properties: {
      linesOfOutput: {
        type: "number",
        description: "The number of lines of output to read."
      },
    },
    required: ["linesOfOutput"]
  }

• src/index.ts:26-72 (registration)

  Tool registration in ListToolsRequestSchema handler, where 'read_terminal_output' is listed among available tools.

    return {
      tools: [
        {
          name: "write_to_terminal",
          description: "Writes text to the active iTerm terminal - often used to run a command in the terminal",
          inputSchema: {
            type: "object",
            properties: {
              command: {
                type: "string",
                description: "The command to run or text to write to the terminal"
              },
            },
            required: ["command"]
          }
        },
        {
          name: "read_terminal_output",
          description: "Reads the output from the active iTerm terminal",
          inputSchema: {
            type: "object",
            properties: {
              linesOfOutput: {
                type: "number",
                description: "The number of lines of output to read."
              },
            },
            required: ["linesOfOutput"]
          }
        },
        {
          name: "send_control_character",
          description: "Sends a control character to the active iTerm terminal (e.g., Control-C)",
          inputSchema: {
            type: "object",
            properties: {
              letter: {
                type: "string",
                description: "The letter corresponding to the control character (e.g., 'C' for Control-C)"
              },
            },
            required: ["letter"]
          }
        }
      ]
    };
  });

• src/TtyOutputReader.ts:6-14 (helper)

  Core helper method TtyOutputReader.call() that retrieves full terminal buffer and returns the last N lines (or all if unspecified). Called directly by the tool handler.

  export default class TtyOutputReader {
    static async call(linesOfOutput?: number) {
      const buffer = await this.retrieveBuffer();
      if (!linesOfOutput) {
        return buffer;
      }
      const lines = buffer.split('\n');
      return lines.slice(-linesOfOutput - 1).join('\n');
    }

• src/TtyOutputReader.ts:16-32 (helper)

  Supporting helper TtyOutputReader.retrieveBuffer() that uses AppleScript via osascript to fetch the full contents of the current iTerm2 session.

    static async retrieveBuffer(): Promise<string> {
      const ascript = `
        tell application "iTerm2"
          tell front window
            tell current session of current tab
              set numRows to number of rows
              set allContent to contents
              return allContent
            end tell
          end tell
        end tell
      `;
      
      const { stdout: finalContent } = await execPromise(`osascript -e '${ascript}'`);
      return finalContent.trim();
    }
  }