Terminal Reader MCP

Instructions

Implementation Reference

• index.js:160-184 (handler)

  The handler function for the get_recent_commands tool. It parses the terminal log using parseLogFile, retrieves the last N (default 5) commands, formats each with exit status, command, and output, and returns them as a single text content block.

  async ({ count = 5 }) => {
    const entries = parseLogFile();
    
    if (entries.length === 0) {
      return {
        content: [{
          type: 'text',
          text: 'No terminal history found.',
        }],
      };
    }
  
    const recent = entries.slice(-count);
    const formatted = recent.map((entry, i) => {
      const exitStatus = entry.exitCode === 0 ? '✓' : `✗ (${entry.exitCode})`;
      return `[${i + 1}] ${exitStatus} $ ${entry.command}\n${entry.output}`;
    }).join('\n\n---\n\n');
    
    return {
      content: [{
        type: 'text',
        text: `Last ${recent.length} commands:\n\n${formatted}`,
      }],
    };
  }

• index.js:151-185 (registration)

  Registration of the get_recent_commands tool using server.registerTool, including name, metadata (title, description), input schema, and handler function.

  server.registerTool(
    'get_recent_commands',
    {
      title: 'Get Recent Commands',
      description: 'Get the last N terminal commands and their outputs.',
      inputSchema: {
        count: z.number().min(1).max(20).default(5).describe('Number of recent commands to retrieve (1-20)'),
      },
    },
    async ({ count = 5 }) => {
      const entries = parseLogFile();
      
      if (entries.length === 0) {
        return {
          content: [{
            type: 'text',
            text: 'No terminal history found.',
          }],
        };
      }
  
      const recent = entries.slice(-count);
      const formatted = recent.map((entry, i) => {
        const exitStatus = entry.exitCode === 0 ? '✓' : `✗ (${entry.exitCode})`;
        return `[${i + 1}] ${exitStatus} $ ${entry.command}\n${entry.output}`;
      }).join('\n\n---\n\n');
      
      return {
        content: [{
          type: 'text',
          text: `Last ${recent.length} commands:\n\n${formatted}`,
        }],
      };
    }
  );

• index.js:156-158 (schema)

  Input schema for the tool using Zod to validate the 'count' parameter (number between 1-20, default 5).

  inputSchema: {
    count: z.number().min(1).max(20).default(5).describe('Number of recent commands to retrieve (1-20)'),
  },

• index.js:29-76 (helper)

  Helper function parseLogFile that reads and parses the terminal history log file into an array of command entries, each containing command, output, exitCode, and optional timestamp.

  function parseLogFile() {
    if (!existsSync(LOG_FILE)) {
      return [];
    }
  
    const content = readFileSync(LOG_FILE, 'utf8');
    const entries = [];
    const blocks = content.split('---CMD---').filter(block => block.trim());
  
    for (const block of blocks) {
      const entry = {
        command: '',
        output: '',
        exitCode: null,
        timestamp: null,
      };
  
      // Extract command (line starting with $)
      const cmdMatch = block.match(/^\s*\$\s*(.+?)(?:\n|---)/m);
      if (cmdMatch) {
        entry.command = cmdMatch[1].trim();
      }
  
      // Extract output
      const outputMatch = block.match(/---OUTPUT---\n([\s\S]*?)(?:---EXIT|---END|$)/);
      if (outputMatch) {
        entry.output = outputMatch[1].trim();
      }
  
      // Extract exit code
      const exitMatch = block.match(/---EXIT:(\d+)---/);
      if (exitMatch) {
        entry.exitCode = parseInt(exitMatch[1], 10);
      }
  
      // Extract timestamp if present
      const timestampMatch = block.match(/---TIMESTAMP:(.+?)---/);
      if (timestampMatch) {
        entry.timestamp = timestampMatch[1];
      }
  
      if (entry.command) {
        entries.push(entry);
      }
    }
  
    return entries;
  }