@markmnl/fmsg-mcp 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+- A sub-address (such as `@user_agent@example.com`, owned by `@user@example.com`) now sends to
+  its owner by default: `send_message`, `reply` and `create_draft` add the owner as a recipient so
+  they can follow and reply to the thread, with a new `include_owner` argument (default true) to
+  leave them off. The owner comes from the API-key token's `owner` claim; the instructions and
+  `whoami` (new `owner` field) name it, and `include_owner` is only offered when the caller may be a
+  sub-address. `FmsgClient.owner()` and the token provider's optional `owner` field expose it.
 - An upload the fmsg host refused part-way, such as a large file PUT to someone else's draft or a
   sent message, no longer hangs until the proxy times out. The server reads the rest of the body
   and answers with the host's reason; if the host closed the connection before giving one, the

package/README.md

@@ -40,6 +40,11 @@ Use the API URL and key for local installation below, or use your provider's API
 with an `Authorization: Bearer fmsgk_...` header. The endpoint must use the fmsg Web API that accepts
 your key.
 
+An agent's key is usually for a **sub-address** such as `@user_agent@example.com`, owned by
+`@user@example.com`. The owner can switch to the sub-address in their client, but can only follow
+and reply to threads they are a participant of. So `send_message`, `reply` and `create_draft` add the
+owner as a recipient unless `include_owner` is false; `whoami` reports the owner.
+
 ### MCP Registry
 
 Find `io.github.markmnl/fmsg-mcp` in the [official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.markmnl%2Ffmsg-mcp).
@@ -128,7 +133,7 @@ See the [TLS reverse-proxy example](docs/http-deployment.md) for a loopback depl
 
 | Tool | What it does |
 |---|---|
-| `whoami` | The address this server acts as, the public API URL (when known), the transport (`stdio` or `http`, which is Streamable HTTP) and short-name defaults |
+| `whoami` | The address this server acts as, its `owner` if it is a sub-address, the public API URL (when known), the transport (`stdio` or `http`, which is Streamable HTTP) and short-name defaults |
 | `resolve_address` | Turn a short name into `@user@domain` (directory, then default domain) |
 | `list_messages` | Inbox, newest first, with previews, attachment types and `size` (`compressed` marks a body sent deflated); reactions hidden and never counted as unread unless `include_reactions` |
 | `list_sent` | Sent messages with per-recipient delivery state |

package/dist/auth.js

@@ -47,9 +47,12 @@ export class ApiKeyCallerProvider {
         this.pendingClients.add(client);
         try {
             const address = await client.address();
+            const owner = await client.owner();
             if (this.closed)
                 throw new Error("server is closing");
-            const entry = { key, caller: { client, address, tokenExpiresAt: async () => (await client.getToken()).expiresAtMs }, lastUsed: Date.now(), active: 0 };
+            const entry = {
+                key, caller: { client, address, ...(owner ? { owner } : {}), tokenExpiresAt: async () => (await client.getToken()).expiresAtMs }, lastUsed: Date.now(), active: 0,
+            };
             this.entries.set(key, entry);
             this.log(safeErrorMessage(`authenticated ${address} (key ${key.slice(0, 8)}…)`));
             return entry;
@@ -93,7 +96,8 @@ export class ApiKeyCallerProvider {
             this.leases.set(lease, entry);
             return {
                 token: key, clientId: entry.caller.address, scopes: [FMSG_SCOPE],
-                expiresAt: Math.floor(expiresAtMs / 1000), extra: { cacheKey: key, callerLease: lease },
+                expiresAt: Math.floor(expiresAtMs / 1000),
+                extra: { cacheKey: key, callerLease: lease, ...(entry.caller.owner ? { owner: entry.caller.owner } : {}) },
             };
         }
         catch (error) {

package/dist/client/client.d.ts

@@ -44,6 +44,8 @@ export declare class FmsgClient {
     get reconnectOnTokenExpiry(): boolean;
     /** The provider's authenticated address, pinned for this client's lifetime. */
     address(signal?: AbortSignal): Promise<string>;
+    /** The address that owns the authenticated sub-address, or undefined when acting as an owner's own address. */
+    owner(signal?: AbortSignal): Promise<string | undefined>;
     getToken(force?: boolean, signal?: AbortSignal): Promise<AccessToken>;
     private startRenewal;
     /** Release credentials and cancel outstanding work when the client is no longer used. */

package/dist/client/client.js

@@ -82,6 +82,10 @@ export class FmsgClient {
     async address(signal) {
         return (await this.getToken(false, signal)).address;
     }
+    /** The address that owns the authenticated sub-address, or undefined when acting as an owner's own address. */
+    async owner(signal) {
+        return (await this.getToken(false, signal)).owner;
+    }
     async getToken(force = false, signal) {
         signal?.throwIfAborted();
         this.lifetime.signal.throwIfAborted();
@@ -125,7 +129,12 @@ export class FmsgClient {
             if (this.boundAddress !== undefined && address !== this.boundAddress)
                 throw new Error("token provider changed the authenticated address; create a new client for a different identity");
             this.boundAddress = address;
-            const token = Object.freeze({ accessToken: value.accessToken, address, expiresAtMs: value.expiresAtMs });
+            const owner = typeof value.owner === "string" ? normalizeFmsgAddress(value.owner) : undefined;
+            if (value.owner !== undefined && !owner)
+                throw new Error("token provider returned an invalid owner address");
+            const token = Object.freeze({
+                accessToken: value.accessToken, address, ...(owner && owner.toLowerCase() !== address.toLowerCase() ? { owner } : {}), expiresAtMs: value.expiresAtMs,
+            });
             this.refreshAtMs = token.expiresAtMs - Math.min(this.options.refreshMarginMs ?? 300_000, (token.expiresAtMs - now) / 2);
             this.token = token;
             return token;

package/dist/client/token-provider.d.ts

@@ -25,3 +25,5 @@ export declare class ApiKeyTokenProvider implements TokenProvider {
     getToken({ apiUrl, signal }: TokenProviderRequest): Promise<AccessToken>;
     close(): void;
 }
+/** The `owner` claim as an address, when it is one and differs from the subject. */
+export declare function ownerOf(payload: Record<string, unknown>, address: string): string | undefined;

package/dist/client/token-provider.js

@@ -25,6 +25,8 @@ export class ApiKeyTokenProvider {
         const address = typeof payload.sub === "string" ? normalizeFmsgAddress(payload.sub) : undefined;
         if (!address)
             throw new Error("token JWT sub is not an fmsg address");
+        // The Web API's `owner` claim names the account a sub-address belongs to; an owner's own token has none.
+        const owner = ownerOf(payload, address);
         const expiries = [
             typeof body.expires_at === "string" ? Date.parse(body.expires_at) : Number.NaN,
             typeof payload.exp === "number" ? payload.exp * 1000 : Number.NaN,
@@ -32,10 +34,15 @@ export class ApiKeyTokenProvider {
         ].filter(Number.isFinite);
         // Never extend the JWT lifetime using a later response expiry or a guessed TTL.
         const expiresAtMs = expiries.length ? Math.min(...expiries) : Number.NaN;
-        return { accessToken: body.access_token, address, expiresAtMs };
+        return { accessToken: body.access_token, address, ...(owner ? { owner } : {}), expiresAtMs };
     }
     close() { this.apiKey = ""; }
 }
+/** The `owner` claim as an address, when it is one and differs from the subject. */
+export function ownerOf(payload, address) {
+    const owner = typeof payload.owner === "string" ? normalizeFmsgAddress(payload.owner) : undefined;
+    return owner && owner.toLowerCase() !== address.toLowerCase() ? owner : undefined;
+}
 // Only the first-party API-key contract requires sub/exp in a JWT. Custom
 // providers supply address/expiry metadata; the client does not decode their tokens.
 function decodeJwtPayload(token) {

package/dist/client/types.d.ts

@@ -103,6 +103,11 @@ export type AccessToken = {
     readonly accessToken: string;
     /** Authenticated fmsg address supplied by the provider; not necessarily a JWT sub. */
     readonly address: string;
+    /**
+     * The address that owns `address` when it is a sub-address (a derived sub-account such as
+     * `@user_agent@example.com`, or a delegated identity); absent when the token is the owner's own.
+     */
+    readonly owner?: string;
     readonly expiresAtMs: number;
 };
 export type OutboundAttachment = {

package/dist/context.d.ts

@@ -4,6 +4,8 @@ import { FmsgClient } from "./client/client.js";
 export type Caller = {
     client: FmsgClient;
     address: string;
+    /** The address that owns `address` when it is a sub-address; the owner sees none of this caller's messages. */
+    owner?: string;
     /** When the current Web API access token expires (ms since epoch), for whoami. */
     tokenExpiresAt: () => Promise<number>;
 };

package/dist/context.js

@@ -7,7 +7,8 @@ export class StaticCallerProvider {
     forRequest() {
         this.caller ??= (async () => {
             const address = await this.client.address();
-            return { client: this.client, address, tokenExpiresAt: async () => (await this.client.getToken()).expiresAtMs };
+            const owner = await this.client.owner();
+            return { client: this.client, address, ...(owner ? { owner } : {}), tokenExpiresAt: async () => (await this.client.getToken()).expiresAtMs };
         })().catch((error) => {
             this.caller = undefined;
             throw error;

package/dist/http.js

@@ -138,7 +138,11 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
     const metadataPath = resource ? `/.well-known/oauth-protected-resource${resource.pathname === "/" ? "" : resource.pathname}` : undefined;
     const metadataUrl = resource ? `${resource.origin}${metadataPath}` : "";
     const shutdown = new AbortController();
-    const mcpHandler = (provider, address) => createMcpHandler(({ authInfo }) => createFmsgMcpServer(provider, config, { ...(authInfo ? { address: address(authInfo) } : {}), shutdown: shutdown.signal }), { onerror: (error) => safeLog(`MCP transport failed: ${error instanceof Error ? error.message : String(error)}`) });
+    const mcpHandler = (provider, address) => createMcpHandler(({ authInfo }) => createFmsgMcpServer(provider, config, {
+        ...(authInfo ? { address: address(authInfo) } : {}),
+        ...(typeof authInfo?.extra?.owner === "string" ? { owner: authInfo.extra.owner } : {}),
+        shutdown: shutdown.signal,
+    }), { onerror: (error) => safeLog(`MCP transport failed: ${error instanceof Error ? error.message : String(error)}`) });
     const oauthHandler = oauthProvider && mcpHandler(oauthProvider, (authInfo) => String(authInfo.extra?.address ?? ""));
     const apiKeyHandler = apiKeyProvider && mcpHandler(apiKeyProvider, (authInfo) => authInfo.clientId);
     const active = new Map();

package/dist/index.js

@@ -125,16 +125,17 @@ async function main() {
         }
         // Resolve the address once so the instructions can name it; never let a slow
         // or unreachable host hold up initialize.
-        const knownAddress = async () => {
+        const knownCaller = async () => {
             if (!cfg.apiUrl || !cfg.apiKey)
                 return undefined;
             const timeout = new Promise((resolve) => setTimeout(() => resolve(undefined), 5000).unref());
-            return Promise.race([provider.forRequest(undefined).then((c) => c.address), timeout]).catch(() => undefined);
+            return Promise.race([provider.forRequest(undefined).then((c) => ({ address: c.address, ...(c.owner ? { owner: c.owner } : {}) })), timeout])
+                .catch(() => undefined);
         };
         const shutdown = new AbortController();
         const handle = serveStdio(async () => {
-            const address = await knownAddress();
-            return createFmsgMcpServer(provider, cfg, { ...(address ? { address } : {}), shutdown: shutdown.signal });
+            const known = await knownCaller();
+            return createFmsgMcpServer(provider, cfg, { ...known, shutdown: shutdown.signal });
         });
         onShutdown(async () => {
             // Let an in-flight wait write its "interrupted" result before the transport closes.

package/dist/instructions.d.ts

@@ -2,6 +2,8 @@ import type { FileRoutes } from "./tools/attachments.js";
 export type InstructionsContext = {
     /** The address this server acts as, when already known (HTTP callers; stdio after a token exchange). */
     address?: string;
+    /** The address that owns `address` when it is a sub-address, when known. */
+    owner?: string;
     /** FMSG_DEFAULT_DOMAIN: a domain, or CALLER_DOMAIN for the caller's own domain. */
     defaultDomain?: string;
     /** Large-file routes this server offers; none when omitted. */

package/dist/instructions.js

@@ -2,11 +2,12 @@
  * Server instructions: returned in the MCP `initialize` result and folded into
  * the model's system prompt by hosts that support them (some chat hosts do not, so
  * nothing a tool needs may live only here). Rules that span tools, each stated once:
- * which address this server acts as, the fmsg terms, the inbox routine, how to
- * send files, the irreversible-send rule and untrusted content. Per-tool detail lives in the tool
- * descriptions; situational guidance in results.
+ * which address this server acts as (and its owner, for a sub-address), the fmsg terms, the inbox
+ * routine, how to send files, the irreversible-send rule and untrusted content. Per-tool detail lives in
+ * the tool descriptions; situational guidance in results. Keep it short: hosts fold it into every prompt.
  */
 import { CALLER_DOMAIN, effectiveDefaultDomain } from "./address.js";
+import { ownerSentence } from "./owner.js";
 /** How to send files, naming only the routes this server offers. */
 function filesParagraph(files) {
     const large = [
@@ -17,8 +18,10 @@ function filesParagraph(files) {
 }
 export function buildInstructions(ctx = {}) {
     const identity = ctx.address
-        ? `you are acting as ${ctx.address}`
+        ? `you are acting as ${ctx.address}${ctx.owner ? `, a sub-address of ${ctx.owner}` : ""}`
         : "call whoami to see which";
+    // An owner's own address needs no owner sentence; an unknown caller gets the conditional one.
+    const owner = ctx.address && !ctx.owner ? "" : ` ${ownerSentence(ctx.owner)}`;
     const domain = effectiveDefaultDomain(ctx.defaultDomain, ctx.address);
     const shortNames = domain
         ? `; short names resolve to @name@${domain}`
@@ -27,7 +30,7 @@ export function buildInstructions(ctx = {}) {
             : "";
     return [
         `This server sends and receives fmsg messages as one fmsg address, and only that one: ${identity}. ` +
-            "Use its tools for everything fmsg; other fmsg tools or local credentials may act as a different address.",
+            `Use its tools for everything fmsg; other fmsg tools or local credentials may act as a different address.${owner}`,
         "fmsg is threaded messaging between @user@domain addresses. Only a thread's first message has a topic; " +
             "replies have none. A reaction is a small message carrying one emoji. Terminal messages (such as reactions) " +
             "cannot be replied or reacted to; no-reply asks recipients not to answer. Added recipients are people " +

package/dist/owner.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Sub-addresses, stated once. `@user_agent@example.com` is a sub-address of `@user@example.com`: the
+ * owner can switch to it in their client, but can only follow and reply to a thread they are a
+ * participant of. So messages a sub-address sends include the owner as a recipient unless the
+ * model passes include_owner: false.
+ */
+import * as z from "zod/v4";
+/** The instructions sentence after the identity: concrete when the owner is known, conditional otherwise. */
+export declare function ownerSentence(owner: string | undefined): string;
+/** The include_owner argument for send-type tools; undefined when the caller is known to be an owner's own address. */
+export declare function includeOwnerSchema(address: string | undefined, owner: string | undefined): z.ZodDefault<z.ZodBoolean> | undefined;
+/** The recipients with the caller's owner appended, unless include_owner is false (unknown: the argument is only registered for possible sub-addresses) or they are already present. */
+export declare function withOwner(caller: {
+    owner?: string;
+}, recipients: string[], includeOwner: unknown): string[];

package/dist/owner.js

@@ -0,0 +1,27 @@
+/**
+ * Sub-addresses, stated once. `@user_agent@example.com` is a sub-address of `@user@example.com`: the
+ * owner can switch to it in their client, but can only follow and reply to a thread they are a
+ * participant of. So messages a sub-address sends include the owner as a recipient unless the
+ * model passes include_owner: false.
+ */
+import * as z from "zod/v4";
+import { sameAddress } from "./address.js";
+/** The instructions sentence after the identity: concrete when the owner is known, conditional otherwise. */
+export function ownerSentence(owner) {
+    return owner
+        ? `Messages you send include ${owner} as a recipient unless include_owner is false, so they can follow and reply.`
+        : "If whoami shows an owner, messages you send include them as a recipient unless include_owner is false.";
+}
+/** The include_owner argument for send-type tools; undefined when the caller is known to be an owner's own address. */
+export function includeOwnerSchema(address, owner) {
+    if (address && !owner)
+        return undefined;
+    return z.boolean().default(true).describe(owner ? `also send to your owner ${owner}` : "also send to your owner, if whoami shows one");
+}
+/** The recipients with the caller's owner appended, unless include_owner is false (unknown: the argument is only registered for possible sub-addresses) or they are already present. */
+export function withOwner(caller, recipients, includeOwner) {
+    const owner = caller.owner;
+    if (!owner || includeOwner === false || recipients.some((r) => sameAddress(r, owner)))
+        return recipients;
+    return [...recipients, owner];
+}

package/dist/server.d.ts

@@ -5,6 +5,8 @@ export declare const SERVER_NAME = "fmsg";
 export type CreateServerOptions = {
     /** The caller's address when already known; makes the instructions name it. */
     address?: string;
+    /** The address that owns the caller's sub-address, when known; the instructions and descriptions then name it. */
+    owner?: string;
     /** Aborted when the process begins shutting down, so wait_for_message returns "interrupted". */
     shutdown?: AbortSignal;
 };

package/dist/server.js

@@ -1,5 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/server";
 import { buildInstructions } from "./instructions.js";
+import { includeOwnerSchema } from "./owner.js";
 import { registerPrompts } from "./prompts.js";
 import { registerResources } from "./resources.js";
 import { fileRoutes } from "./tools/attachments.js";
@@ -20,11 +21,15 @@ export const SERVER_NAME = "fmsg";
 export function createFmsgMcpServer(provider, config, options = {}) {
     const instructions = buildInstructions({
         ...(options.address ? { address: options.address } : {}),
+        ...(options.owner ? { owner: options.owner } : {}),
         ...(config.defaultDomain ? { defaultDomain: config.defaultDomain } : {}),
         files: fileRoutes(config),
     });
     const server = new McpServer({ name: SERVER_NAME, title: "fmsg", version: VERSION }, { instructions });
-    const deps = { provider, config, ...(options.shutdown ? { shutdown: options.shutdown } : {}) };
+    const includeOwner = includeOwnerSchema(options.address, options.owner);
+    const deps = {
+        provider, config, ...(includeOwner ? { includeOwner } : {}), ...(options.shutdown ? { shutdown: options.shutdown } : {}),
+    };
     registerIdentityTools(server, deps);
     registerListTools(server, deps);
     registerReadTools(server, deps);

package/dist/tools/common.d.ts

@@ -7,6 +7,8 @@ import { type Caller, type CallerProvider } from "../context.js";
 export type ToolDeps = {
     provider: CallerProvider;
     config: Config;
+    /** The include_owner argument of send-type tools; absent when the caller is known to be an owner's own address. */
+    includeOwner?: z.ZodDefault<z.ZodBoolean>;
     /** Aborted when the server begins shutting down; long waits then return early. */
     shutdown?: AbortSignal;
 };

package/dist/tools/draft.js

@@ -1,6 +1,7 @@
 import * as z from "zod/v4";
 import { downloadBaseUrl } from "../download.js";
 import { toolError } from "../errors.js";
+import { withOwner } from "../owner.js";
 import { addressList, headerValue, isoTime } from "../render.js";
 import { CHECKSUM_HEADER, UPLOAD_ENCODINGS, draftUploadUrlTemplate } from "../upload.js";
 import { attachmentInput, base64Hint, draftWithAttachments, fileRoutes, prepareAttachments } from "./attachments.js";
@@ -10,6 +11,7 @@ import { IMMUTABLE, IMPORTANT, NO_REPLY, UPLOAD_STEPS, hintOutput, redactionNote
 export const registerDraftTools = (server, deps) => {
     const baseUrl = downloadBaseUrl(deps.config);
     const routes = fileRoutes(deps.config);
+    const includeOwner = deps.includeOwner ? { include_owner: deps.includeOwner } : {};
     server.registerTool("create_draft", {
         title: "Create fmsg draft",
         description: "Create an unsent draft: a new message, or a reply when reply_to is given (reply rules and reply-all apply). " +
@@ -25,6 +27,7 @@ export const registerDraftTools = (server, deps) => {
             important: z.boolean().default(false).describe(IMPORTANT),
             no_reply: z.boolean().default(false).describe(NO_REPLY),
             allow_no_reply: z.boolean().default(false).describe("draft a reply even though the parent asked for no replies"),
+            ...includeOwner,
             attachments: z.array(attachmentInput(deps.config)).optional().describe("files to attach now"),
         }),
         outputSchema: outputObject({
@@ -48,7 +51,7 @@ export const registerDraftTools = (server, deps) => {
             hint: hintOutput,
         }),
         annotations: { ...SENDS, destructiveHint: false },
-    }, async ({ to, topic, reply_to, body, type, important, no_reply, allow_no_reply, attachments }, ctx) => {
+    }, async ({ to, topic, reply_to, body, type, important, no_reply, allow_no_reply, include_owner, attachments }, ctx) => {
         if (reply_to && topic)
             return toolError("a reply has no topic: pass topic only for a new message");
         if (!reply_to && !to?.length)
@@ -68,6 +71,7 @@ export const registerDraftTools = (server, deps) => {
             else {
                 ({ to: recipients, resolved } = resolveRecipients(to, resolverFor(deps, caller)));
             }
+            recipients = withOwner(caller, recipients, include_owner);
             const outbound = await prepareAttachments(attachments, deps.config);
             const hint = base64Hint(attachments, routes);
             const draft = await draftWithAttachments(caller.client, {

package/dist/tools/identity.js

@@ -9,10 +9,11 @@ const TRANSPORT_LABELS = { stdio: "stdio", http: "Streamable HTTP" };
 export const registerIdentityTools = (server, deps) => {
     server.registerTool("whoami", {
         title: "Show fmsg identity",
-        description: "Report the fmsg address this server acts as, the fmsg Web API URL and how short names resolve; the text " +
-            "also gives the server version. Call this first if unsure who you are sending as.",
+        description: "Report the fmsg address this server acts as, its owner if it is a sub-address, the fmsg Web API URL and how " +
+            "short names resolve; the text also gives the server version. Call this first if unsure who you are sending as.",
         outputSchema: outputObject({
             address: z.string(),
+            owner: z.string().optional().describe("owner of this sub-address, included as a recipient of messages you send unless include_owner is false; absent for an owner's own address"),
             api_url: z.string().nullable(),
             token_expires_at: z.string().nullable().describe("internal: when the server's current upstream access token expires; it is renewed automatically, so no action is needed"),
             transport: openEnum(["stdio", "http"], "http is Streamable HTTP"),
@@ -27,6 +28,7 @@ export const registerIdentityTools = (server, deps) => {
         const transport = TRANSPORT_LABELS[deps.config.transport];
         const structured = {
             address: caller.address,
+            ...(caller.owner ? { owner: caller.owner } : {}),
             api_url: deps.config.apiPublicUrl ?? null,
             token_expires_at: expires,
             transport: deps.config.transport,
@@ -39,6 +41,8 @@ export const registerIdentityTools = (server, deps) => {
                 : `You are ${addressText(caller.address)}, connected over ${transport}.`,
             `Access is renewed automatically. Server version ${VERSION}.`,
         ];
+        if (caller.owner)
+            lines.push(`Sub-address of ${addressText(caller.owner)}, who is a recipient of messages you send unless include_owner is false.`);
         if (defaultDomain)
             lines.push(`Short names resolve to @name@${defaultDomain}.`);
         if (directoryNames.length)

package/dist/tools/send.js

@@ -1,6 +1,7 @@
 import * as z from "zod/v4";
 import { resolveAddress, sameAddress } from "../address.js";
 import { toolError } from "../errors.js";
+import { withOwner } from "../owner.js";
 import { addressList, addressText, attachmentType, headerValue, isoTime, participantsOf, sortAttachments } from "../render.js";
 import { attachmentInput, base64Hint, fileRoutes, prepareAttachments, sendWithAttachments } from "./attachments.js";
 import { SENDS, attachmentItem, idSchema, ok, outputObject, resolverFor, withCaller } from "./common.js";
@@ -99,6 +100,7 @@ export function resolvedNote(resolved) {
 export const registerSendTools = (server, deps) => {
     const attachments = z.array(attachmentInput(deps.config)).optional().describe("files");
     const guidance = attachmentGuidance(deps.config);
+    const includeOwner = deps.includeOwner ? { include_owner: deps.includeOwner } : {};
     const routes = fileRoutes(deps.config);
     server.registerTool("send_message", {
         title: "Send new fmsg message",
@@ -113,12 +115,14 @@ export const registerSendTools = (server, deps) => {
             type: z.string().default("text/markdown; charset=utf-8").describe("body media type"),
             important: z.boolean().default(false).describe(IMPORTANT),
             no_reply: z.boolean().default(false).describe(NO_REPLY),
+            ...includeOwner,
             attachments,
         }),
         outputSchema: sentOutput,
         annotations: SENDS,
-    }, async ({ to, topic, body, type, important, no_reply, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
-        const { to: recipients, resolved } = resolveRecipients(to, resolverFor(deps, caller));
+    }, async ({ to, topic, body, type, important, no_reply, include_owner, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        const { to: resolvedTo, resolved } = resolveRecipients(to, resolverFor(deps, caller));
+        const recipients = withOwner(caller, resolvedTo, include_owner);
         const outbound = await prepareAttachments(attachments, deps.config);
         const hint = base64Hint(attachments, routes);
         const sent = await sendWithAttachments(caller.client, { to: recipients, topic, body, type, important, noReply: no_reply }, outbound, signal);
@@ -156,16 +160,18 @@ export const registerSendTools = (server, deps) => {
             important: z.boolean().default(false).describe(IMPORTANT),
             no_reply: z.boolean().default(false).describe(NO_REPLY),
             allow_no_reply: z.boolean().default(false).describe("reply even though the parent asked for no replies"),
+            ...includeOwner,
             attachments,
         }),
         outputSchema: sentOutput,
         annotations: SENDS,
-    }, async ({ id, body, recipients, type, important, no_reply, allow_no_reply, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+    }, async ({ id, body, recipients, type, important, no_reply, allow_no_reply, include_owner, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const parent = await caller.client.getMessage(id, signal);
         const target = replyRecipients(deps, caller, parent, recipients, allow_no_reply);
         if ("content" in target)
             return target;
-        const { to, resolved } = target;
+        const { resolved } = target;
+        const to = withOwner(caller, target.to, include_owner);
         const outbound = await prepareAttachments(attachments, deps.config);
         const hint = base64Hint(attachments, routes);
         const sent = await sendWithAttachments(caller.client, { to, pid: parent.id, body, type, important, noReply: no_reply }, outbound, signal);

package/docs/token-providers.md

@@ -16,6 +16,7 @@ interface TokenProvider {
   }): Promise<{
     accessToken: string;
     address: string;
+    owner?: string;
     expiresAtMs: number;
   }>;
   close?(): void;
@@ -36,6 +37,8 @@ Sharing a provider between clients risks mixing grants or closing another client
   case, and a finite future expiry in milliseconds since the Unix epoch. Use trusted
   authorization/exchange metadata; do not invent an expiry or infer identity from an
   unverified incoming token. The generic client does not decode provider tokens.
+- Optionally return `owner`, the address that owns `address` when it is a sub-address (the Web
+  API's `owner` claim); omit it for an owner's own address. `FmsgClient.owner()` exposes it.
 - Honour `signal` for all network work. It aborts when renewal times out, the client
   closes, or all callers waiting for that renewal cancel. Reject on failed/revoked
   authorization; never fall back to an owner token, API key or another grant.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@markmnl/fmsg-mcp",
   "mcpName": "io.github.markmnl/fmsg-mcp",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "MCP server for fmsg: send and receive federated messages from any AI agent via a deployed fmsg Web API",
   "type": "module",
   "license": "MIT",

package/server.json

@@ -8,13 +8,13 @@
     "url": "https://github.com/markmnl/fmsg-mcp",
     "source": "github"
   },
-  "version": "1.1.1",
+  "version": "1.2.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@markmnl/fmsg-mcp",
-      "version": "1.1.1",
+      "version": "1.2.0",
       "transport": {
         "type": "stdio"
       },