get_messages

Instructions

Implementation Reference

• src/tools.js:98-119 (registration)

  Registration of the "get_messages" tool on the MCP server. It accepts terminal_name (required) and delete_after_read (boolean, default true) inputs and calls the list() function from messages.js.

  server.tool(
    "get_messages",
    "Read messages sent to this terminal. Returns all messages and optionally deletes them after reading.",
    {
      terminal_name: nameSchema.describe("Your terminal name"),
      delete_after_read: z
        .boolean()
        .default(true)
        .describe("Delete messages after reading (default: true)"),
    },
    async ({ terminal_name, delete_after_read }) => {
      const messages = list(terminal_name, { deleteAfterRead: delete_after_read });
      if (messages.length === 0) {
        return {
          content: [{ type: "text", text: `No messages for "${terminal_name}".` }],
        };
      }
      return {
        content: [{ type: "text", text: renderMessages(terminal_name, messages) }],
      };
    },
  );

• src/tools.js:108-118 (handler)

  Handler function for get_messages: calls list(terminal_name, { deleteAfterRead }) from messages.js, returns formatted messages or a 'no messages' response.

  async ({ terminal_name, delete_after_read }) => {
    const messages = list(terminal_name, { deleteAfterRead: delete_after_read });
    if (messages.length === 0) {
      return {
        content: [{ type: "text", text: `No messages for "${terminal_name}".` }],
      };
    }
    return {
      content: [{ type: "text", text: renderMessages(terminal_name, messages) }],
    };
  },

• src/tools.js:170-176 (helper)

  Helper renderMessages() formats the list of messages into a human-readable text response.

  function renderMessages(to, messages) {
    const parts = messages.map(
      (m, i) =>
        `--- Message ${i + 1} ---\nFrom: ${m.from ?? "?"}\nTime: ${m.sentAt ?? "?"}\nSummary: ${m.summary ?? ""}\n\n${m.content ?? ""}`,
    );
    return `${messages.length} message(s) for "${to}":\n\n${parts.join("\n\n")}`;
  }

• src/messages.js:63-105 (handler)

  The core list() function from messages.js that reads all stored messages for a recipient, filters out stale ones, optionally deletes them after reading, and returns the result.

  export function list(to, { deleteAfterRead = false } = {}, now = Date.now) {
    assertValidName(to);
    ensureDirs();
  
    const prefix = filePrefix(to);
    let entries;
    try {
      entries = readdirSync(messagesDir()).filter(
        (f) => f.startsWith(prefix) && f.endsWith(".json"),
      );
    } catch {
      return [];
    }
    entries.sort();
  
    const out = [];
    const cutoff = now() - MESSAGE_TTL_MS;
  
    for (const file of entries) {
      const path = join(messagesDir(), file);
      const data = /** @type {{from?: string, sentAt?: string, summary?: string, content?: string} | null} */ (
        readJsonSafe(path)
      );
      if (!data) {
        tryUnlink(path);
        continue;
      }
      const sentMs = data.sentAt ? Date.parse(data.sentAt) : NaN;
      if (Number.isFinite(sentMs) && sentMs < cutoff) {
        tryUnlink(path);
        continue;
      }
      out.push({ file, ...data });
    }
  
    if (deleteAfterRead) {
      for (const m of out) {
        tryUnlink(join(messagesDir(), m.file));
      }
    }
  
    return out;
  }

• src/tools.js:102-106 (schema)

  Input schema for get_messages: terminal_name (validated name pattern) and delete_after_read (boolean, defaults to true).

  terminal_name: nameSchema.describe("Your terminal name"),
  delete_after_read: z
    .boolean()
    .default(true)
    .describe("Delete messages after reading (default: true)"),