send_message

Instructions

Implementation Reference

• src/tools.js:64-96 (registration)

  Tool 'send_message' is registered with MCP server via server.tool(), defining the schema (from, to, summary, content) and the handler callback.

  server.tool(
    "send_message",
    "Send a message to another terminal. The target terminal can read it with get_messages.",
    {
      from: nameSchema.describe("Your terminal name (the sender)"),
      to: nameSchema.describe("Target terminal name (the receiver)"),
      summary: z
        .string()
        .max(MAX_SUMMARY_BYTES, `Summary must be <= ${MAX_SUMMARY_BYTES} bytes`)
        .describe("Brief summary of the message"),
      content: z
        .string()
        .max(MAX_CONTENT_BYTES, `Content must be <= ${MAX_CONTENT_BYTES} bytes`)
        .describe("The full message content to share"),
    },
    async ({ from, to, summary, content }) => {
      try {
        const { sentAt } = send({ from, to, summary, content });
        return {
          content: [
            {
              type: "text",
              text: `Message sent to "${to}" at ${sentAt}.\nSummary: ${summary}\nSize: ${content.length} chars`,
            },
          ],
        };
      } catch (err) {
        return {
          content: [{ type: "text", text: `Failed to send: ${errorMessage(err)}` }],
        };
      }
    },
  );

• src/messages.js:32-54 (handler)

  The actual send() function validates inputs, writes the message as a JSON file atomically to disk, enforces queue caps, and returns the sent timestamp.

  export function send({ from, to, summary, content }, now = Date.now) {
    assertValidName(from);
    assertValidName(to);
    assertSummarySize(summary);
    assertContentSize(content);
    ensureDirs();
  
    const timestamp = now();
    const suffix = randomBytes(4).toString("hex");
    const filename = `${filePrefix(to)}${String(timestamp).padStart(15, "0")}_${suffix}.json`;
    const path = join(messagesDir(), filename);
  
    writeJsonAtomic(path, {
      from,
      to,
      summary,
      content,
      sentAt: new Date(timestamp).toISOString(),
    });
  
    enforceQueueCap(to);
    return { filename, sentAt: new Date(timestamp).toISOString() };
  }

• src/tools.js:67-78 (schema)

  Input schema for send_message: 'from' and 'to' use nameSchema (regex validated), 'summary' capped at MAX_SUMMARY_BYTES, 'content' capped at MAX_CONTENT_BYTES.

  {
    from: nameSchema.describe("Your terminal name (the sender)"),
    to: nameSchema.describe("Target terminal name (the receiver)"),
    summary: z
      .string()
      .max(MAX_SUMMARY_BYTES, `Summary must be <= ${MAX_SUMMARY_BYTES} bytes`)
      .describe("Brief summary of the message"),
    content: z
      .string()
      .max(MAX_CONTENT_BYTES, `Content must be <= ${MAX_CONTENT_BYTES} bytes`)
      .describe("The full message content to share"),
  },

• src/validators.js:12-19 (helper)

  assertValidName() validates that terminal names match the pattern [A-Za-z0-9_-]{1,32}, used by send() to validate 'from' and 'to'.

  export function assertValidName(name) {
    if (typeof name !== "string" || !NAME_PATTERN.test(name)) {
      throw new Error(
        `Invalid terminal name: must match ${NAME_PATTERN} (got ${JSON.stringify(name)})`,
      );
    }
    return name;
  }

• src/storage.js:47-73 (helper)

  writeJsonAtomic() writes data to a temp file then atomically renames it, used by send() to persist the message file.

  export function writeJsonAtomic(filePath, data) {
    const dir = dirname(filePath);
    const tmp = join(dir, `.tmp-${randomBytes(6).toString("hex")}`);
    writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
    try {
      renameSync(tmp, filePath);
    } catch (err) {
      try {
        unlinkSync(tmp);
      } catch {
        // best effort
      }
      throw err;
    }
  }
  
  /**
   * @param {string} filePath
   * @returns {unknown | null}
   */
  export function readJsonSafe(filePath) {
    try {
      return JSON.parse(readFileSync(filePath, "utf-8"));
    } catch {
      return null;
    }
  }