@markmnl/fmsg-mcp 0.1.0

package/dist/resources.js

@@ -0,0 +1,37 @@
+import { ResourceTemplate, ProtocolError, ProtocolErrorCode } from "@modelcontextprotocol/server";
+import { normalizeMessageId } from "./client/message-id.js";
+import { callerFor } from "./context.js";
+import { DATA_NOT_INSTRUCTIONS, fence, messageHeader } from "./render.js";
+import { assembleThread, renderThread } from "./thread.js";
+export function registerResources(server, deps) {
+    server.registerResource("message", new ResourceTemplate("fmsg://message/{id}", { list: undefined }), { title: "fmsg message", description: "One fmsg message with headers and body", mimeType: "text/markdown" }, async (uri, { id }, ctx) => {
+        let mid;
+        try {
+            mid = normalizeMessageId(String(id));
+        }
+        catch {
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, `invalid fmsg message id "${String(id)}"`);
+        }
+        const caller = await callerFor(deps.provider, ctx);
+        const message = await caller.client.getMessage(mid, ctx.mcpReq.signal);
+        const text = await caller.client.getText(message, ctx.mcpReq.signal);
+        const body = text === null ? `[non-text body: ${message.type ?? "?"}, ${message.size ?? 0} bytes]` : `${DATA_NOT_INSTRUCTIONS}\n\n${fence(text)}`;
+        return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: `${messageHeader(message)}\n\n${body}` }] };
+    });
+    server.registerResource("thread", new ResourceTemplate("fmsg://thread/{id}", { list: undefined }), { title: "fmsg thread", description: "The lineage of messages from the thread root to the given message", mimeType: "text/markdown" }, async (uri, { id }, ctx) => {
+        let mid;
+        try {
+            mid = normalizeMessageId(String(id));
+        }
+        catch {
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, `invalid fmsg message id "${String(id)}"`);
+        }
+        const caller = await callerFor(deps.provider, ctx);
+        const thread = await assembleThread(caller.client, caller.address, mid, {
+            maxMessages: 100,
+            maxBodyBytesPerMessage: 65_536,
+            maxTotalBytes: 1_048_576,
+        }, ctx.mcpReq.signal);
+        return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: renderThread(thread) }] };
+    });
+}

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import type { Config } from "./config.js";
+import type { CallerProvider } from "./context.js";
+export declare const SERVER_NAME = "fmsg";
+/**
+ * Build an fmsg MCP server. Registration only — no I/O — so the same factory
+ * serves one stdio connection or one HTTP request.
+ */
+export declare function createFmsgMcpServer(provider: CallerProvider, config: Config): McpServer;

package/dist/server.js

@@ -0,0 +1,26 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { registerPrompts } from "./prompts.js";
+import { registerResources } from "./resources.js";
+import { registerIdentityTools } from "./tools/identity.js";
+import { registerListTools } from "./tools/list.js";
+import { registerReadTools } from "./tools/read.js";
+import { registerSendTools } from "./tools/send.js";
+import { registerWaitTools } from "./tools/wait.js";
+import { VERSION } from "./version.js";
+export const SERVER_NAME = "fmsg";
+/**
+ * Build an fmsg MCP server. Registration only — no I/O — so the same factory
+ * serves one stdio connection or one HTTP request.
+ */
+export function createFmsgMcpServer(provider, config) {
+    const server = new McpServer({ name: SERVER_NAME, title: "fmsg", version: VERSION });
+    const deps = { provider, config };
+    registerIdentityTools(server, deps);
+    registerListTools(server, deps);
+    registerReadTools(server, deps);
+    registerSendTools(server, deps);
+    registerWaitTools(server, deps);
+    registerResources(server, deps);
+    registerPrompts(server);
+    return server;
+}

package/dist/thread.d.ts

@@ -0,0 +1,42 @@
+import { FmsgClient } from "./client/client.js";
+export type ThreadCaps = {
+    maxMessages: number;
+    maxBodyBytesPerMessage: number;
+    maxTotalBytes: number;
+};
+export type AssembledMessage = {
+    id: string;
+    pid: string | null;
+    visible: boolean;
+    from?: string;
+    to?: string[];
+    time: string | null;
+    time_posix: number | null;
+    topic?: string;
+    type?: string;
+    size?: number;
+    body: string | null;
+    body_truncated: boolean;
+    attachments: Array<{
+        filename: string;
+        size: number;
+        type?: string;
+    }>;
+};
+export type AssembledThread = {
+    root_id: string;
+    trigger_id: string;
+    complete: boolean;
+    source: "thread_messages" | "pid_walk";
+    participants: string[];
+    reply_target_id: string;
+    terminal: boolean;
+    messages: AssembledMessage[];
+    omitted: number;
+};
+/**
+ * Reconstruct the direct lineage of a message (root → trigger). Uses the host's
+ * thread endpoint and falls back to a pid walk when the host declines (too deep / too large).
+ */
+export declare function assembleThread(client: FmsgClient, self: string, triggerId: string, caps: ThreadCaps, signal?: AbortSignal): Promise<AssembledThread>;
+export declare function renderThread(thread: AssembledThread): string;

package/dist/thread.js

@@ -0,0 +1,176 @@
+import { FmsgClient, FmsgHttpError } from "./client/client.js";
+import { DATA_NOT_INSTRUCTIONS, fence, isoTime, participantsOf, truncateUtf8, truncationNote } from "./render.js";
+function nonReactions(messages) {
+    // Reactions are terminal no-reply leaves; they never appear on a lineage, so nothing to filter here.
+    return messages;
+}
+async function fromThreadMessages(client, thread, caps, signal) {
+    const all = nonReactions(thread.messages);
+    const omitted = Math.max(0, all.length - caps.maxMessages);
+    const kept = omitted > 0 ? all.slice(all.length - caps.maxMessages) : all;
+    let budget = caps.maxTotalBytes;
+    const out = [];
+    for (const m of kept) {
+        let body = null;
+        let truncated = false;
+        if (m.visible && m.body) {
+            let text = null;
+            if (typeof m.body.text === "string")
+                text = m.body.text;
+            else if (m.body.download && FmsgClient.isText({ type: m.body.type }) && m.body.size <= caps.maxBodyBytesPerMessage * 4) {
+                const { data } = await client.downloadPath(m.body.download, signal);
+                text = Buffer.from(data).toString("utf8");
+            }
+            if (text !== null) {
+                const limit = Math.max(0, Math.min(caps.maxBodyBytesPerMessage, budget));
+                const t = truncateUtf8(text, limit);
+                body = t.text;
+                truncated = t.truncated;
+                budget -= t.shown;
+            }
+        }
+        out.push({
+            id: m.id,
+            pid: m.pid ?? null,
+            visible: m.visible,
+            ...(m.from ? { from: m.from } : {}),
+            ...(m.to ? { to: m.to } : {}),
+            time: isoTime(m.time),
+            time_posix: typeof m.time === "number" ? m.time : null,
+            ...(m.topic ? { topic: m.topic } : {}),
+            ...(m.type ? { type: m.type } : {}),
+            ...(typeof m.size === "number" ? { size: m.size } : {}),
+            body,
+            body_truncated: truncated,
+            attachments: (m.attachments ?? []).map((a) => ({ filename: a.filename, size: a.size, type: a.type })),
+        });
+    }
+    return { messages: out, omitted };
+}
+async function fromPidWalk(client, triggerId, caps, signal) {
+    const chain = [];
+    let id = triggerId;
+    let complete = true;
+    while (id && chain.length < caps.maxMessages) {
+        let msg;
+        try {
+            msg = await client.getMessage(id, signal);
+        }
+        catch (error) {
+            if (error instanceof FmsgHttpError && (error.status === 404 || error.status === 403)) {
+                complete = false;
+                break;
+            }
+            throw error;
+        }
+        chain.push(msg);
+        id = msg.pid ?? null;
+    }
+    if (id)
+        complete = false;
+    chain.reverse();
+    let budget = caps.maxTotalBytes;
+    const messages = [];
+    for (const m of chain) {
+        let body = null;
+        let truncated = false;
+        const text = await client.getText(m, signal);
+        if (text !== null) {
+            const t = truncateUtf8(text, Math.max(0, Math.min(caps.maxBodyBytesPerMessage, budget)));
+            body = t.text;
+            truncated = t.truncated;
+            budget -= t.shown;
+        }
+        messages.push({
+            id: m.id,
+            pid: m.pid ?? null,
+            visible: true,
+            from: m.from,
+            to: m.to,
+            time: isoTime(m.time),
+            time_posix: typeof m.time === "number" ? m.time : null,
+            ...(m.topic ? { topic: m.topic } : {}),
+            ...(m.type ? { type: m.type } : {}),
+            ...(typeof m.size === "number" ? { size: m.size } : {}),
+            body,
+            body_truncated: truncated,
+            attachments: (m.attachments ?? []).map((a) => ({ filename: a.filename, size: a.size })),
+        });
+    }
+    const last = chain[chain.length - 1];
+    return { root_id: chain[0].id, complete, messages, last };
+}
+/**
+ * Reconstruct the direct lineage of a message (root → trigger). Uses the host's
+ * thread endpoint and falls back to a pid walk when the host declines (too deep / too large).
+ */
+export async function assembleThread(client, self, triggerId, caps, signal) {
+    const trigger = await client.getMessage(triggerId, signal);
+    const participants = participantsOf(trigger).filter((a) => a !== self.toLowerCase());
+    try {
+        const thread = await client.getThreadMessages(triggerId, signal);
+        const { messages, omitted } = await fromThreadMessages(client, thread, caps, signal);
+        return {
+            root_id: thread.root_id,
+            trigger_id: thread.trigger_id,
+            complete: thread.complete && omitted === 0,
+            source: "thread_messages",
+            participants,
+            reply_target_id: trigger.id,
+            terminal: trigger.terminal === true,
+            messages,
+            omitted,
+        };
+    }
+    catch (error) {
+        if (!(error instanceof FmsgHttpError && (error.status === 422 || error.status === 413 || error.status === 404 || error.status === 501))) {
+            throw error;
+        }
+        const walk = await fromPidWalk(client, triggerId, caps, signal);
+        return {
+            root_id: walk.root_id,
+            trigger_id: triggerId,
+            complete: walk.complete,
+            source: "pid_walk",
+            participants,
+            reply_target_id: trigger.id,
+            terminal: trigger.terminal === true,
+            messages: walk.messages,
+            omitted: 0,
+        };
+    }
+}
+export function renderThread(thread) {
+    const lines = [];
+    const root = thread.messages[0];
+    lines.push(`**fmsg thread** root ${thread.root_id} · ${thread.messages.length} message${thread.messages.length === 1 ? "" : "s"} on the lineage to ${thread.trigger_id}${thread.complete ? "" : " (incomplete)"}`);
+    if (root?.topic)
+        lines.push(`Topic: ${root.topic}`);
+    if (thread.omitted > 0)
+        lines.push(`(${thread.omitted} earlier message${thread.omitted === 1 ? "" : "s"} omitted)`);
+    lines.push(`Participants (reply-all default): ${thread.participants.join(", ") || "(none)"}`);
+    lines.push("");
+    lines.push(DATA_NOT_INSTRUCTIONS);
+    for (const m of thread.messages) {
+        lines.push("");
+        if (!m.visible) {
+            lines.push(`--- message ${m.id} [not visible to you] ---`);
+            continue;
+        }
+        lines.push(`--- message ${m.id} from ${m.from ?? "?"} · ${m.time ?? "draft"}${m.pid ? ` · reply to ${m.pid}` : ""} ---`);
+        if (m.attachments.length)
+            lines.push(`attachments: ${m.attachments.map((a) => `${a.filename} (${a.size} bytes)`).join(", ")}`);
+        if (m.body === null)
+            lines.push(`[non-text body: ${m.type ?? "?"}, ${m.size ?? 0} bytes — use get_message / download_attachment]`);
+        else {
+            lines.push(fence(m.body.trimEnd()));
+            if (m.body_truncated)
+                lines.push(truncationNote({ text: "", truncated: true, shown: Buffer.byteLength(m.body), total: m.size ?? 0 }, `call get_message ${m.id} for the full body`).trim());
+        }
+    }
+    lines.push("");
+    lines.push(thread.terminal
+        ? `Message ${thread.reply_target_id} is terminal: it cannot be replied to.`
+        : `To continue this thread, reply to message ${thread.reply_target_id} (the reply tool).`);
+    return lines.join("\n");
+}

package/dist/tools/common.d.ts

@@ -0,0 +1,62 @@
+import type { CallToolResult, McpServer, ServerContext, ToolAnnotations } from "@modelcontextprotocol/server";
+import * as z from "zod/v4";
+import type { FmsgMessage } from "../client/types.js";
+import type { Config } from "../config.js";
+import { type Caller, type CallerProvider } from "../context.js";
+export type ToolDeps = {
+    provider: CallerProvider;
+    config: Config;
+};
+export declare const READ_ONLY: ToolAnnotations;
+export declare const SENDS: ToolAnnotations;
+export declare const idSchema: z.ZodString;
+export declare const attachmentItem: z.ZodObject<{
+    filename: z.ZodString;
+    size: z.ZodNumber;
+}, z.core.$strip>;
+export declare const deliveryItem: z.ZodObject<{
+    addr: z.ZodString;
+    status: z.ZodEnum<{
+        delivered: "delivered";
+        pending: "pending";
+        failed: "failed";
+    }>;
+    time: z.ZodNullable<z.ZodString>;
+    code: z.ZodNullable<z.ZodNumber>;
+    via: z.ZodEnum<{
+        to: "to";
+        add_to: "add_to";
+    }>;
+}, z.core.$strip>;
+export declare const messageItem: z.ZodObject<{
+    id: z.ZodString;
+    pid: z.ZodNullable<z.ZodString>;
+    from: z.ZodString;
+    to: z.ZodArray<z.ZodString>;
+    added: z.ZodArray<z.ZodString>;
+    topic: z.ZodString;
+    time: z.ZodNullable<z.ZodString>;
+    time_posix: z.ZodNullable<z.ZodNumber>;
+    read: z.ZodNullable<z.ZodBoolean>;
+    important: z.ZodBoolean;
+    no_reply: z.ZodBoolean;
+    terminal: z.ZodBoolean;
+    type: z.ZodString;
+    size: z.ZodNumber;
+    preview: z.ZodString;
+    attachments: z.ZodArray<z.ZodObject<{
+        filename: z.ZodString;
+        size: z.ZodNumber;
+    }, z.core.$strip>>;
+    reactions: z.ZodArray<z.ZodObject<{
+        emoji: z.ZodString;
+        from: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type MessageItem = z.infer<typeof messageItem>;
+export declare function toItem(m: FmsgMessage, self: string): MessageItem;
+export declare function deliveryOf(m: FmsgMessage): z.infer<typeof deliveryItem>[];
+export declare function ok(text: string, structured: Record<string, unknown>): CallToolResult;
+/** Resolve the caller and run a tool body, turning any failure into an `isError` result. */
+export declare function withCaller(deps: ToolDeps, ctx: ServerContext, body: (caller: Caller, signal: AbortSignal) => Promise<CallToolResult>): Promise<CallToolResult>;
+export type Register = (server: McpServer, deps: ToolDeps) => void;

package/dist/tools/common.js

@@ -0,0 +1,88 @@
+import * as z from "zod/v4";
+import { callerFor } from "../context.js";
+import { describeError, toolError } from "../errors.js";
+import { isoTime, preview } from "../render.js";
+export const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+export const SENDS = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
+export const idSchema = z.string().regex(/^[0-9]+$/u, "fmsg message ids are decimal integers").describe("fmsg message id");
+export const attachmentItem = z.object({ filename: z.string(), size: z.number() });
+export const deliveryItem = z.object({
+    addr: z.string(),
+    status: z.enum(["delivered", "pending", "failed"]),
+    time: z.string().nullable(),
+    code: z.number().nullable(),
+    via: z.enum(["to", "add_to"]),
+});
+export const messageItem = z.object({
+    id: z.string(),
+    pid: z.string().nullable(),
+    from: z.string(),
+    to: z.array(z.string()),
+    added: z.array(z.string()).describe("recipients added later via add-to"),
+    topic: z.string(),
+    time: z.string().nullable().describe("ISO-8601; null for drafts"),
+    time_posix: z.number().nullable(),
+    read: z.boolean().nullable().describe("null when not applicable (your own sent messages)"),
+    important: z.boolean(),
+    no_reply: z.boolean(),
+    terminal: z.boolean(),
+    type: z.string(),
+    size: z.number(),
+    preview: z.string(),
+    attachments: z.array(attachmentItem),
+    reactions: z.array(z.object({ emoji: z.string(), from: z.array(z.string()) })),
+});
+export function toItem(m, self) {
+    const mine = m.from.toLowerCase() === self.toLowerCase();
+    return {
+        id: m.id,
+        pid: m.pid ?? null,
+        from: m.from,
+        to: m.to,
+        added: (m.add_to ?? []).flatMap((b) => b.to ?? []),
+        topic: m.topic ?? "",
+        time: isoTime(m.time),
+        time_posix: typeof m.time === "number" ? m.time : null,
+        read: mine ? null : (m.read ?? null),
+        important: m.important === true,
+        no_reply: m.no_reply === true,
+        terminal: m.terminal === true,
+        type: m.type ?? "",
+        size: m.size ?? 0,
+        preview: preview(m),
+        attachments: (m.attachments ?? []).map((a) => ({ filename: a.filename, size: a.size })),
+        reactions: (m.reactions ?? []).map((r) => ({ emoji: r.emoji, from: r.from })),
+    };
+}
+export function deliveryOf(m) {
+    const out = [];
+    const push = (addr, entry, via) => {
+        const time = entry?.time_delivered ?? null;
+        const code = entry?.response_code ?? null;
+        const status = time !== null ? "delivered" : code !== null ? "failed" : "pending";
+        out.push({ addr, status, time, code, via });
+    };
+    m.to.forEach((addr, i) => push(addr, m.to_delivery?.[i], "to"));
+    for (const batch of m.add_to ?? [])
+        (batch.to ?? []).forEach((addr, i) => push(addr, batch.to_delivery?.[i], "add_to"));
+    return out;
+}
+export function ok(text, structured) {
+    return { content: [{ type: "text", text }], structuredContent: structured };
+}
+/** Resolve the caller and run a tool body, turning any failure into an `isError` result. */
+export async function withCaller(deps, ctx, body) {
+    let caller;
+    try {
+        caller = await callerFor(deps.provider, ctx);
+    }
+    catch (error) {
+        return toolError(describeError(error));
+    }
+    try {
+        return await body(caller, ctx.mcpReq.signal);
+    }
+    catch (error) {
+        return toolError(describeError(error, caller.address));
+    }
+}

package/dist/tools/identity.d.ts

@@ -0,0 +1,2 @@
+import { type Register } from "./common.js";
+export declare const registerIdentityTools: Register;

package/dist/tools/identity.js

@@ -0,0 +1,58 @@
+import * as z from "zod/v4";
+import { resolveAddress } from "../address.js";
+import { isoTime } from "../render.js";
+import { READ_ONLY, ok, withCaller } from "./common.js";
+import { toolError } from "../errors.js";
+export const registerIdentityTools = (server, deps) => {
+    server.registerTool("whoami", {
+        title: "Show fmsg identity",
+        description: "Report the fmsg address this server acts as (derived from the API key), the fmsg Web API URL, " +
+            "when the current access token expires (it is renewed automatically; no action needed), and the " +
+            "address-resolution defaults. Call this first if unsure who you are sending as.",
+        outputSchema: z.object({
+            address: z.string(),
+            api_url: z.string(),
+            token_expires_at: z.string().nullable(),
+            transport: z.enum(["stdio", "http"]),
+            default_domain: z.string().nullable(),
+            directory_names: z.array(z.string()),
+        }),
+        annotations: { ...READ_ONLY, openWorldHint: false },
+    }, async (ctx) => withCaller(deps, ctx, async (caller) => {
+        const expires = isoTime((await caller.tokenExpiresAt()) / 1000);
+        const structured = {
+            address: caller.address,
+            api_url: caller.client.apiUrl,
+            token_expires_at: expires,
+            transport: deps.config.transport,
+            default_domain: deps.config.defaultDomain ?? null,
+            directory_names: Object.keys(deps.config.directory ?? {}),
+        };
+        const lines = [
+            `You are **${caller.address}** on ${caller.client.apiUrl} (${deps.config.transport}).`,
+            `Access token expires ${expires ?? "unknown"} and is renewed automatically.`,
+        ];
+        if (deps.config.defaultDomain)
+            lines.push(`Short names resolve to @name@${deps.config.defaultDomain}.`);
+        if (structured.directory_names.length)
+            lines.push(`Directory names: ${structured.directory_names.join(", ")}.`);
+        return ok(lines.join("\n"), structured);
+    }));
+    server.registerTool("resolve_address", {
+        title: "Resolve fmsg address",
+        description: "Resolve a short name to a full fmsg address without sending anything: a literal @user@domain is returned " +
+            "as-is, otherwise a configured directory entry is used, otherwise @name@<default domain>. " +
+            "Fails when nothing matches so you can ask the user for the full address.",
+        inputSchema: z.object({ name: z.string().describe("Full fmsg address (@user@domain) or a short name") }),
+        outputSchema: z.object({ address: z.string(), resolution: z.enum(["literal", "directory", "default_domain"]) }),
+        annotations: { ...READ_ONLY, openWorldHint: false },
+    }, async ({ name }) => {
+        try {
+            const resolved = resolveAddress(name, deps.config);
+            return ok(`${name} → ${resolved.address} (${resolved.resolution})`, resolved);
+        }
+        catch (error) {
+            return toolError(error instanceof Error ? error.message : String(error));
+        }
+    });
+};

package/dist/tools/list.d.ts

@@ -0,0 +1,2 @@
+import { type Register } from "./common.js";
+export declare const registerListTools: Register;

package/dist/tools/list.js

@@ -0,0 +1,72 @@
+import * as z from "zod/v4";
+import { messageLine } from "../render.js";
+import { READ_ONLY, deliveryItem, deliveryOf, messageItem, ok, toItem, withCaller } from "./common.js";
+const pageInput = {
+    limit: z.number().int().min(1).max(100).default(20).describe("page size (host maximum 100)"),
+    offset: z.number().int().min(0).default(0).describe("number of newest messages to skip"),
+    include_reactions: z.boolean().default(false).describe("also list reaction messages (normally hidden)"),
+};
+export const registerListTools = (server, deps) => {
+    server.registerTool("list_messages", {
+        title: "List inbox",
+        description: "List messages received by this address, newest first. Each item carries the id, sender, recipients, topic, " +
+            "time, read state, flags, size, attachment names and a short preview. Reaction messages are hidden unless " +
+            "include_reactions is true. Use get_message for a full body and get_thread for the conversation around a message.",
+        inputSchema: z.object({
+            ...pageInput,
+            unread_only: z.boolean().default(false).describe("keep only unread messages from the fetched page"),
+        }),
+        outputSchema: z.object({
+            messages: z.array(messageItem),
+            count: z.number(),
+            offset: z.number(),
+            next_offset: z.number().nullable().describe("offset for the next page, or null when this page was short"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ limit, offset, include_reactions, unread_only }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        const page = await caller.client.listInbox(limit, offset, signal);
+        const shown = page.filter((m) => (include_reactions || m.reaction === null || m.reaction === undefined) && (!unread_only || m.read === false));
+        const structured = {
+            messages: shown.map((m) => toItem(m, caller.address)),
+            count: shown.length,
+            offset,
+            next_offset: page.length === limit ? offset + limit : null,
+        };
+        const text = shown.length
+            ? `${shown.length} message${shown.length === 1 ? "" : "s"} (offset ${offset}):\n${shown.map((m) => messageLine(m, caller.address)).join("\n")}`
+            : `No ${unread_only ? "unread " : ""}messages at offset ${offset}.`;
+        return ok(text, structured);
+    }));
+    server.registerTool("list_sent", {
+        title: "List sent messages",
+        description: "List messages sent by this address (including unsent drafts, shown with time null), newest first, with " +
+            "per-recipient delivery state. Use delivery_status for one message's detail.",
+        inputSchema: z.object(pageInput),
+        outputSchema: z.object({
+            messages: z.array(messageItem.extend({ delivery: z.array(deliveryItem) })),
+            count: z.number(),
+            offset: z.number(),
+            next_offset: z.number().nullable(),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ limit, offset, include_reactions }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        const page = await caller.client.listSent(limit, offset, signal);
+        const shown = page.filter((m) => include_reactions || m.reaction === null || m.reaction === undefined);
+        const structured = {
+            messages: shown.map((m) => ({ ...toItem(m, caller.address), delivery: deliveryOf(m) })),
+            count: shown.length,
+            offset,
+            next_offset: page.length === limit ? offset + limit : null,
+        };
+        const text = shown.length
+            ? `${shown.length} sent message${shown.length === 1 ? "" : "s"} (offset ${offset}):\n${shown
+                .map((m) => {
+                const d = deliveryOf(m);
+                const summary = d.length ? ` · delivered ${d.filter((x) => x.status === "delivered").length}/${d.length}` : "";
+                return `${messageLine(m, caller.address)}${summary}`;
+            })
+                .join("\n")}`
+            : `No sent messages at offset ${offset}.`;
+        return ok(text, structured);
+    }));
+};

package/dist/tools/read.d.ts

@@ -0,0 +1,2 @@
+import { type Register } from "./common.js";
+export declare const registerReadTools: Register;