@markmnl/fmsg-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Mennell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# fmsg-mcp
+
+[![Tests](https://github.com/markmnl/fmsg-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/markmnl/fmsg-mcp/actions/workflows/tests.yml)
+[![npm](https://img.shields.io/npm/v/%40markmnl%2Ffmsg-mcp)](https://www.npmjs.com/package/@markmnl/fmsg-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+An [MCP](https://modelcontextprotocol.io) server that gives any AI agent its own
+[fmsg](https://github.com/markmnl/fmsg) address: send messages, follow threads, react, exchange
+attachments and wait for replies, through a deployed
+[fmsg Web API](https://github.com/markmnl/fmsg-webapi). Works with Claude Code, Claude Desktop,
+Cursor, VS Code, claude.ai remote connectors and any other MCP host.
+
+- **stdio** for local hosts: one address per server process, configured by two environment variables.
+- **Streamable HTTP** for shared or remote deployments: one endpoint serving many users, each
+  authenticated by their own fmsg API key.
+- The fmsg Web API client is exported for reuse: `import { FmsgClient } from "@markmnl/fmsg-mcp/client"`.
+
+## 1. Get an fmsg address and API key
+
+You send as an fmsg address, authenticated by an API key (`fmsgk_…`) issued by your fmsg host:
+
+- **No host yet?** Create an account at a public fmsg host such as [fmsg.io](https://fmsg.io) and
+  add an agent (sub-account) to get an API URL and key.
+- **Self-hosting?** Run the stack with [fmsg-docker](https://github.com/markmnl/fmsg-docker) and issue
+  a key with `fmsg-webapi api-key create`.
+
+## 2. Install
+
+Requires Node.js 22 or later.
+
+### Claude Code
+
+```sh
+claude mcp add fmsg --scope user \
+  --env FMSG_API_URL=https://api.example.com \
+  --env FMSG_API_KEY=fmsgk_... \
+  -- npx -y @markmnl/fmsg-mcp
+```
+
+Then in any session: *"Send @bob@example.com a note about the release"*, *"What's in my fmsg inbox?"*,
+*"Wait for Bob's reply and answer it"*. `/fmsg:chat` and `/fmsg:reply` are available as prompts.
+
+### Claude Desktop, Cursor, VS Code and other stdio hosts
+
+Add a server entry with the same command; only the config file differs:
+
+```json
+{
+  "mcpServers": {
+    "fmsg": {
+      "command": "npx",
+      "args": ["-y", "@markmnl/fmsg-mcp"],
+      "env": { "FMSG_API_URL": "https://api.example.com", "FMSG_API_KEY": "fmsgk_..." }
+    }
+  }
+}
+```
+
+(Claude Desktop: `claude_desktop_config.json`; Cursor: `.cursor/mcp.json`; VS Code: `.vscode/mcp.json`
+under `"servers"` with `"type": "stdio"`.)
+
+### Remote (Streamable HTTP) mode
+
+Run one server for many users. Each client sends **its own** fmsg API key as a bearer token; the
+server exchanges it at the fmsg host and acts as that address. `FMSG_API_KEY` must not be set.
+
+```sh
+FMSG_API_URL=https://api.example.com npx -y @markmnl/fmsg-mcp --http 0.0.0.0:8765
+# or
+docker build -t fmsg-mcp . && docker run -e FMSG_API_URL=https://api.example.com -p 8765:8765 fmsg-mcp
+```
+
+The MCP endpoint is `/mcp`; `/healthz` reports liveness. Point a host at it with
+`Authorization: Bearer fmsgk_...` — for claude.ai, add a custom connector with that URL and header;
+for Claude Code, `claude mcp add --transport http fmsg https://mcp.example.com/mcp --header "Authorization: Bearer fmsgk_..."`.
+
+Deploy behind a TLS-terminating reverse proxy and set `FMSG_MCP_ALLOWED_HOSTS` to the public hostname
+when binding to a non-loopback address. `wait_for_message` holds a request open for up to
+`FMSG_MCP_WAIT_MAX_SECONDS` (230), so give the proxy an idle timeout of at least 240 s.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `whoami` | The address this server acts as, the API URL and token expiry |
+| `resolve_address` | Turn a short name into `@user@domain` (directory, then default domain) |
+| `list_messages` | Inbox, newest first, with previews; reactions hidden; optional unread filter |
+| `list_sent` | Sent messages with per-recipient delivery state |
+| `get_message` | One message with headers, full text body, attachments and reactions |
+| `get_thread` | The lineage from the thread root to a message, with gaps for messages you cannot see |
+| `send_message` | Start a new thread; sends immediately (fmsg messages are immutable) |
+| `reply` | Reply into a thread; reply-all by default, refuses terminal and no-reply parents |
+| `add_recipients` | Add recipients to a sent message |
+| `react` | Set or clear your emoji reaction |
+| `mark_read` | Mark received messages read |
+| `download_attachment` | Fetch an attachment inline (base64, images as image blocks) or, over stdio, save it to disk |
+| `delivery_status` | Per-recipient delivery times and host response codes |
+| `wait_for_message` | Block until the next inbound message (WebSocket push), batched per thread, with thread context |
+
+Every tool returns readable Markdown plus `structuredContent`. Ids are decimal strings. Message
+bodies are labelled as data from other parties, not instructions.
+
+Resources `fmsg://message/{id}` and `fmsg://thread/{id}` expose the same content to hosts that
+attach resources; prompts `chat` and `reply` script the wait → reply loop and a guided reply.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `FMSG_API_URL` | — | Base URL of the fmsg Web API (required) |
+| `FMSG_API_KEY` | — | `fmsgk_…` key; stdio mode only |
+| `FMSG_DEFAULT_DOMAIN` | — | Lets short names resolve: `bob` → `@bob@<domain>` |
+| `FMSG_DIRECTORY` | — | JSON file mapping short names to full addresses |
+| `FMSG_MCP_WAIT_MAX_SECONDS` | `230` | Cap on one `wait_for_message` call |
+| `FMSG_MCP_DOWNLOAD_DIR` | — | Restrict `download_attachment` `save_to` to this directory (stdio) |
+| `FMSG_MCP_HOST` / `FMSG_MCP_PORT` | `127.0.0.1` / `8765` | HTTP bind address (or `--http host:port`) |
+| `FMSG_MCP_ALLOWED_HOSTS` | loopback names | Comma-separated `Host` header allowlist for HTTP mode |
+| `FMSG_MCP_ALLOWED_ORIGINS` | same as hosts | `Origin` allowlist for browser-based callers |
+| `FMSG_MCP_KEY_CACHE_MAX` / `FMSG_MCP_KEY_CACHE_TTL_SECONDS` | `500` / `1800` | HTTP mode per-key client cache |
+
+The API key is exchanged for a short-lived access token that the server renews automatically.
+
+## Safety
+
+- Sent messages cannot be edited or recalled; send tools say so in their descriptions and are
+  annotated `destructiveHint` so hosts can ask for confirmation.
+- API keys, tokens and other secret-shaped strings are redacted from outbound bodies, topics and
+  error text; the count of redactions is reported.
+- Nothing about message size or acceptance is assumed: the fmsg host's own responses and delivery
+  codes are surfaced verbatim.
+- See [SECURITY.md](./SECURITY.md).
+
+## Using the client library
+
+```ts
+import { FmsgClient } from "@markmnl/fmsg-mcp/client";
+
+const client = new FmsgClient("https://api.example.com", process.env.FMSG_API_KEY!);
+console.log(await client.address());
+const inbox = await client.listInbox(10);
+await client.send({ to: ["@bob@example.com"], topic: "Hi", body: "Hello from code" });
+```
+
+## Development
+
+```sh
+npm ci
+npm run typecheck && npm run build && npm test
+npx @modelcontextprotocol/inspector node dist/index.js          # stdio, with FMSG_API_URL/FMSG_API_KEY set
+bash .github/scripts/run-fmsg-docker-e2e.sh                     # end to end on two real fmsg stacks
+```
+
+See [AGENTS.md](./AGENTS.md) for layout and conventions.
+
+[MIT licensed](./LICENSE)

package/dist/address.d.ts

@@ -0,0 +1,18 @@
+/** Normalise an fmsg address to `@user@domain` (lower-cased). Returns undefined when malformed. */
+export declare function normalizeFmsgAddress(value: string): string | undefined;
+export declare function isFmsgAddress(value: string): boolean;
+export type Resolution = "literal" | "directory" | "default_domain";
+export type AddressResolver = {
+    defaultDomain?: string;
+    directory?: Record<string, string>;
+};
+export type ResolvedAddress = {
+    address: string;
+    resolution: Resolution;
+};
+/**
+ * Resolve a full address or short name: literal `@user@domain` first, then a
+ * configured directory entry, then `@name@<default domain>`.
+ */
+export declare function resolveAddress(name: string, resolver?: AddressResolver): ResolvedAddress;
+export declare function resolveAddresses(names: string[], resolver?: AddressResolver): string[];

package/dist/address.js

@@ -0,0 +1,50 @@
+const ADDRESS = /^@([^@\s/]+)@([^@\s/]+)$/u;
+/** Normalise an fmsg address to `@user@domain` (lower-cased). Returns undefined when malformed. */
+export function normalizeFmsgAddress(value) {
+    const trimmed = value.trim();
+    const match = ADDRESS.exec(trimmed);
+    if (!match)
+        return undefined;
+    return `@${match[1].toLowerCase()}@${match[2].toLowerCase()}`;
+}
+export function isFmsgAddress(value) {
+    return normalizeFmsgAddress(value) !== undefined;
+}
+/**
+ * Resolve a full address or short name: literal `@user@domain` first, then a
+ * configured directory entry, then `@name@<default domain>`.
+ */
+export function resolveAddress(name, resolver = {}) {
+    const trimmed = name.trim();
+    const literal = normalizeFmsgAddress(trimmed);
+    if (literal)
+        return { address: literal, resolution: "literal" };
+    if (trimmed === "" || /[@\s/]/u.test(trimmed)) {
+        throw new Error(`"${name}" is not an fmsg address (@user@domain) or a resolvable short name`);
+    }
+    const key = trimmed.toLowerCase();
+    const directory = resolver.directory ?? {};
+    for (const [entry, target] of Object.entries(directory)) {
+        if (entry.toLowerCase() === key) {
+            const address = normalizeFmsgAddress(target);
+            if (!address)
+                throw new Error(`directory entry "${entry}" maps to an invalid address "${target}"`);
+            return { address, resolution: "directory" };
+        }
+    }
+    if (resolver.defaultDomain) {
+        const address = normalizeFmsgAddress(`@${key}@${resolver.defaultDomain}`);
+        if (address)
+            return { address, resolution: "default_domain" };
+    }
+    throw new Error(`"${name}" is not a full fmsg address and no directory entry or default domain resolves it; ask for the full @user@domain address`);
+}
+export function resolveAddresses(names, resolver = {}) {
+    const out = [];
+    for (const name of names) {
+        const { address } = resolveAddress(name, resolver);
+        if (!out.includes(address))
+            out.push(address);
+    }
+    return out;
+}

package/dist/auth.d.ts

@@ -0,0 +1,21 @@
+import { type AuthInfo, type OAuthTokenVerifier } from "@modelcontextprotocol/server";
+import type { Config } from "./config.js";
+import type { Caller, CallerProvider } from "./context.js";
+export declare const FMSG_SCOPE = "fmsg";
+/**
+ * HTTP mode: each request carries an fmsg API key as its bearer token. The key
+ * is exchanged once at the fmsg host, and the resulting client (which renews
+ * its own JWT) is cached by the key's hash. Raw keys are never stored or logged.
+ */
+export declare class ApiKeyCallerProvider implements CallerProvider, OAuthTokenVerifier {
+    private readonly config;
+    private readonly log;
+    private readonly entries;
+    constructor(config: Config, log?: (line: string) => void);
+    static cacheKey(apiKey: string): string;
+    private evict;
+    /** Bearer verifier for the MCP gate: exchange the key, return the caller's identity. */
+    verifyAccessToken(token: string): Promise<AuthInfo>;
+    forRequest(authInfo: AuthInfo | undefined): Promise<Caller>;
+    get size(): number;
+}

package/dist/auth.js

@@ -0,0 +1,84 @@
+import { createHash } from "node:crypto";
+import { OAuthError, OAuthErrorCode } from "@modelcontextprotocol/server";
+import { FmsgClient, FmsgHttpError } from "./client/client.js";
+export const FMSG_SCOPE = "fmsg";
+/**
+ * HTTP mode: each request carries an fmsg API key as its bearer token. The key
+ * is exchanged once at the fmsg host, and the resulting client (which renews
+ * its own JWT) is cached by the key's hash. Raw keys are never stored or logged.
+ */
+export class ApiKeyCallerProvider {
+    config;
+    log;
+    entries = new Map();
+    constructor(config, log = () => undefined) {
+        this.config = config;
+        this.log = log;
+    }
+    static cacheKey(apiKey) {
+        return createHash("sha256").update(apiKey).digest("hex");
+    }
+    evict() {
+        const now = Date.now();
+        for (const [key, entry] of this.entries) {
+            if (now - entry.lastUsed > this.config.http.keyCacheTtlMs)
+                this.entries.delete(key);
+        }
+        while (this.entries.size > this.config.http.keyCacheMax) {
+            const oldest = [...this.entries.entries()].sort((a, b) => a[1].lastUsed - b[1].lastUsed)[0];
+            if (!oldest)
+                break;
+            this.entries.delete(oldest[0]);
+        }
+    }
+    /** Bearer verifier for the MCP gate: exchange the key, return the caller's identity. */
+    async verifyAccessToken(token) {
+        if (!token.startsWith("fmsgk_")) {
+            throw new OAuthError(OAuthErrorCode.InvalidToken, "bearer token must be an fmsg API key (fmsgk_...)");
+        }
+        const key = ApiKeyCallerProvider.cacheKey(token);
+        let entry = this.entries.get(key);
+        if (!entry) {
+            const client = new FmsgClient(this.config.apiUrl, token);
+            let address;
+            try {
+                address = await client.address();
+            }
+            catch (error) {
+                if (error instanceof FmsgHttpError && (error.status === 401 || error.status === 403 || error.status === 400)) {
+                    this.log(`rejected api key ${key.slice(0, 8)}…: ${error.status} ${error.message}`);
+                    throw new OAuthError(OAuthErrorCode.InvalidToken, `fmsg host rejected the API key: ${error.message}`);
+                }
+                this.log(`token exchange failed for ${key.slice(0, 8)}…: ${error instanceof Error ? error.message : String(error)}`);
+                throw new OAuthError(OAuthErrorCode.ServerError, "fmsg host unavailable for token exchange");
+            }
+            entry = {
+                caller: { client, address, tokenExpiresAt: async () => (await client.getToken()).expiresAtMs },
+                lastUsed: Date.now(),
+            };
+            this.entries.set(key, entry);
+            this.evict();
+            this.log(`authenticated ${address} (key ${key.slice(0, 8)}…)`);
+        }
+        entry.lastUsed = Date.now();
+        const expiresAtMs = await entry.caller.tokenExpiresAt();
+        return {
+            token: key,
+            clientId: entry.caller.address,
+            scopes: [FMSG_SCOPE],
+            expiresAt: Math.floor(expiresAtMs / 1000),
+            extra: { cacheKey: key },
+        };
+    }
+    async forRequest(authInfo) {
+        const key = typeof authInfo?.extra?.cacheKey === "string" ? authInfo.extra.cacheKey : authInfo?.token;
+        const entry = key ? this.entries.get(key) : undefined;
+        if (!entry)
+            throw new Error("not authenticated: send your fmsg API key as `Authorization: Bearer fmsgk_...`");
+        entry.lastUsed = Date.now();
+        return entry.caller;
+    }
+    get size() {
+        return this.entries.size;
+    }
+}

package/dist/client/client.d.ts

@@ -0,0 +1,83 @@
+import type { AccessToken, Attachment, FmsgMessage, ReactResult, SendInput, SendResult, Thread } from "./types.js";
+export type FetchLike = typeof fetch;
+export type FmsgClientOptions = {
+    fetch?: FetchLike;
+    /** Refresh the access token this long before it expires (default 5 minutes). */
+    refreshMarginMs?: number;
+    /** Per-request timeout (default 60 s). */
+    timeoutMs?: number;
+};
+/** An HTTP error from the fmsg Web API, with the status and the host's own error text. */
+export declare class FmsgHttpError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    /** Machine-readable `code` from the body, when the host sends one (thread routes). */
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, method: string, path: string, 
+    /** Machine-readable `code` from the body, when the host sends one (thread routes). */
+    code?: string | undefined);
+}
+/**
+ * Client for the fmsg Web API (FMSG-003). Exchanges an `fmsgk_` API key for a
+ * short-lived JWT, refreshes it ahead of expiry, and retries once on 401.
+ */
+export declare class FmsgClient {
+    private readonly apiKey;
+    private readonly options;
+    readonly apiUrl: string;
+    private token?;
+    private tokenPromise?;
+    constructor(apiUrl: string, apiKey: string, options?: FmsgClientOptions);
+    private get fetchImpl();
+    /** The address this client acts as (from the JWT `sub`), exchanging the key if needed. */
+    address(): Promise<string>;
+    getToken(force?: boolean): Promise<AccessToken>;
+    private exchangeToken;
+    private request;
+    private json;
+    listInbox(limit?: number, offset?: number, signal?: AbortSignal): Promise<FmsgMessage[]>;
+    listSent(limit?: number, offset?: number, signal?: AbortSignal): Promise<FmsgMessage[]>;
+    getMessage(id: string, signal?: AbortSignal): Promise<FmsgMessage>;
+    /** Raw message body bytes. */
+    getData(id: string, signal?: AbortSignal): Promise<{
+        data: Uint8Array;
+        contentType?: string;
+    }>;
+    /** Whether `short_text` already holds the complete body. */
+    static shortTextIsComplete(message: FmsgMessage): boolean;
+    static isText(message: {
+        type?: string;
+    }): boolean;
+    /** Full body text for text-like messages; null for binary bodies. */
+    getText(message: FmsgMessage, signal?: AbortSignal): Promise<string | null>;
+    getThreadMessages(id: string, signal?: AbortSignal): Promise<Thread>;
+    getThreadText(id: string, signal?: AbortSignal): Promise<string>;
+    /** Download by a `download` path returned from thread/messages (`/fmsg/...`). */
+    downloadPath(path: string, signal?: AbortSignal): Promise<{
+        data: Uint8Array;
+        contentType?: string;
+    }>;
+    markRead(id: string, signal?: AbortSignal): Promise<{
+        id: string;
+        time_read: number | null;
+    }>;
+    addRecipients(id: string, addTo: string[], signal?: AbortSignal): Promise<{
+        id: string;
+        added: number;
+    }>;
+    react(id: string, emoji: string | null, signal?: AbortSignal): Promise<ReactResult>;
+    downloadAttachment(id: string, filename: string, signal?: AbortSignal): Promise<{
+        data: Uint8Array;
+        contentType?: string;
+    }>;
+    deleteMessage(id: string, signal?: AbortSignal): Promise<void>;
+    private createDraft;
+    uploadAttachment(draftId: string, attachment: {
+        filename: string;
+        data: Uint8Array;
+        contentType?: string;
+    }, signal?: AbortSignal): Promise<Attachment>;
+    /** Draft → attach → send. The draft is deleted if any step after creation fails. */
+    send(input: SendInput): Promise<SendResult>;
+}