@markmnl/fmsg-mcp 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+- Add optional `FMSG_API_PUBLIC_URL`: the Web API URL `whoami` reports to users, while requests
+  keep using `FMSG_API_URL`. It defaults to `FMSG_API_URL`, except that HTTP mode no longer
+  reports a cleartext (internal or loopback) upstream URL. `whoami`'s `api_url` is therefore
+  nullable and is `null` when no public URL is known.
 - Add HTTP-only `get_attachment_download_url` and authenticated binary attachment GETs. Links
   contain no credentials; downloads reuse caller authentication and OAuth read scope, stream the
   original bytes, and keep Web API access checks authoritative. API-key deployments configure

package/README.md

@@ -125,7 +125,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 API URL and token expiry |
+| `whoami` | The address this server acts as, the public API URL (when known) 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 |
@@ -154,6 +154,7 @@ attach resources; prompts `chat` and `reply` script the wait → reply loop and
 |---|---|---|
 | `FMSG_API_URL` | — | Base URL of the fmsg Web API (required) |
 | `FMSG_API_KEY` | — | `fmsgk_…` key; stdio mode only |
+| `FMSG_API_PUBLIC_URL` | `FMSG_API_URL` (HTTP mode: only if HTTPS) | Web API URL reported to users by `whoami`; never used for requests. Set it when the server reaches the Web API at an internal address. Without it, HTTP mode reports no URL for a cleartext `FMSG_API_URL`. Validated like `FMSG_API_URL` |
 | `FMSG_MCP_AUTH_MODE` | `api-key` | HTTP authentication: `api-key` or `oauth`; see [OAuth settings](docs/oauth.md#operator-configuration) |
 | `FMSG_MCP_PUBLIC_URL` | OAuth resource URL, otherwise unset | Public MCP endpoint, including `/mcp`; enables the HTTP download-link tool. HTTPS required except loopback; in OAuth mode must equal `FMSG_MCP_OAUTH_RESOURCE_URL` |
 | `FMSG_ALLOW_INSECURE_HTTP` | disabled | Set to `1` only to permit cleartext API access on a trusted development/private network; loopback HTTP is allowed by default |

package/dist/client/url.d.ts

@@ -1,4 +1,4 @@
 /** Hosts for which cleartext loopback development is safe by default. */
 export declare function isLoopbackHost(host: string): boolean;
-export declare function normalizeApiUrl(value: string, allowInsecureHttp?: boolean): string;
+export declare function normalizeApiUrl(value: string, allowInsecureHttp?: boolean, name?: string): string;
 export declare function normalizeOrigin(value: string): string;

package/dist/client/url.js

@@ -2,21 +2,21 @@
 export function isLoopbackHost(host) {
     return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
 }
-export function normalizeApiUrl(value, allowInsecureHttp = false) {
+export function normalizeApiUrl(value, allowInsecureHttp = false, name = "FMSG_API_URL") {
     let url;
     try {
         url = new URL(value);
     }
     catch {
-        throw new Error("FMSG_API_URL must be an absolute http(s) URL");
+        throw new Error(`${name} must be an absolute http(s) URL`);
     }
     if (url.protocol !== "https:" && url.protocol !== "http:")
-        throw new Error("FMSG_API_URL must be an http(s) URL");
+        throw new Error(`${name} must be an http(s) URL`);
     if (url.username || url.password || url.search || url.hash) {
-        throw new Error("FMSG_API_URL must not contain credentials, a query string or a fragment");
+        throw new Error(`${name} must not contain credentials, a query string or a fragment`);
     }
     if (url.protocol === "http:" && !isLoopbackHost(url.hostname) && !allowInsecureHttp) {
-        throw new Error("FMSG_API_URL must use HTTPS outside loopback; explicitly enable FMSG_ALLOW_INSECURE_HTTP=1 only for a trusted development/private network");
+        throw new Error(`${name} must use HTTPS outside loopback; explicitly enable FMSG_ALLOW_INSECURE_HTTP=1 only for a trusted development/private network`);
     }
     return url.href.replace(/\/+$/u, "");
 }

package/dist/config.d.ts

@@ -15,6 +15,12 @@ export type HttpConfig = {
 export type Config = {
     transport: Transport;
     apiUrl: string;
+    /**
+     * The Web API URL shown to users (whoami). FMSG_API_PUBLIC_URL when set; otherwise FMSG_API_URL,
+     * except over HTTP where a cleartext upstream (typically a private or loopback address the
+     * server reaches internally) is not shown. Never used for requests.
+     */
+    apiPublicUrl?: string;
     /** Explicit opt-in for cleartext upstream traffic outside loopback. */
     allowInsecureHttp?: boolean;
     /** Only set in stdio mode. */

package/dist/config.js

@@ -39,6 +39,22 @@ function loadDirectory(path) {
     }
     return out;
 }
+/**
+ * Resolve the Web API URL shown to users. An explicit FMSG_API_PUBLIC_URL is validated like
+ * FMSG_API_URL. Without it, stdio shows FMSG_API_URL (the user's own configuration), while HTTP
+ * shows it only when it is HTTPS: a cleartext upstream on a hosted server is an internal address
+ * that means nothing to remote clients.
+ */
+function resolveApiPublicUrl(env, transport, apiUrl, allowInsecureHttp) {
+    const explicit = env.FMSG_API_PUBLIC_URL?.trim();
+    if (explicit)
+        return normalizeApiUrl(explicit, allowInsecureHttp, "FMSG_API_PUBLIC_URL");
+    if (!apiUrl)
+        return undefined;
+    if (transport === "http" && !apiUrl.startsWith("https:"))
+        return undefined;
+    return apiUrl;
+}
 export function loadConfig(env, transport, overrides = {}, options = {}) {
     const requireCredentials = options.requireCredentials ?? true;
     const oauth = loadOAuthConfig(env, transport);
@@ -48,6 +64,7 @@ export function loadConfig(env, transport, overrides = {}, options = {}) {
     }
     const allowInsecureHttp = env.FMSG_ALLOW_INSECURE_HTTP === "1";
     const normalizedApiUrl = apiUrl ? normalizeApiUrl(apiUrl, allowInsecureHttp) : "";
+    const apiPublicUrl = resolveApiPublicUrl(env, transport, normalizedApiUrl, allowInsecureHttp);
     const apiKey = env.FMSG_API_KEY?.trim();
     if (transport === "stdio" && apiKey && !apiKey.startsWith("fmsgk_"))
         throw new Error("FMSG_API_KEY must start with fmsgk_");
@@ -71,6 +88,7 @@ export function loadConfig(env, transport, overrides = {}, options = {}) {
     return {
         transport,
         apiUrl: normalizedApiUrl,
+        ...(apiPublicUrl ? { apiPublicUrl } : {}),
         ...(oauth ? { oauth } : {}),
         allowInsecureHttp,
         ...(transport === "stdio" && apiKey ? { apiKey } : {}),

package/dist/tools/identity.js

@@ -6,12 +6,13 @@ 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 (from the authenticated connection), the fmsg Web API URL, " +
+        description: "Report the fmsg address this server acts as (from the authenticated connection), the fmsg Web API URL " +
+            "(null when the server does not publish it), " +
             "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(),
+            api_url: z.string().nullable(),
             token_expires_at: z.string().nullable(),
             transport: z.enum(["stdio", "http"]),
             default_domain: z.string().nullable(),
@@ -22,14 +23,16 @@ export const registerIdentityTools = (server, deps) => {
         const expires = isoTime((await caller.tokenExpiresAt()) / 1000);
         const structured = {
             address: caller.address,
-            api_url: caller.client.apiUrl,
+            api_url: deps.config.apiPublicUrl ?? null,
             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}).`,
+            deps.config.apiPublicUrl
+                ? `You are **${caller.address}** on ${deps.config.apiPublicUrl} (${deps.config.transport}).`
+                : `You are **${caller.address}** (${deps.config.transport}).`,
             `Access token expires ${expires ?? "unknown"} and is renewed automatically.`,
         ];
         if (deps.config.defaultDomain)

package/docs/http-deployment.md

@@ -13,7 +13,12 @@ FMSG_MCP_ALLOWED_ORIGINS=https://mcp.example.com,https://app.example.com \
 npx -y @markmnl/fmsg-mcp --http 127.0.0.1:8765
 ```
 
-`FMSG_API_KEY` must be unset in HTTP mode. Include only browser origins you use. Behind TLS,
+`FMSG_API_KEY` must be unset in HTTP mode. Include only browser origins you use.
+
+If the server reaches the Web API at an internal address instead, for example
+`FMSG_API_URL=http://10.0.0.5:8000` with `FMSG_ALLOW_INSECURE_HTTP=1` on a private network, also set
+`FMSG_API_PUBLIC_URL=https://api.example.com` so `whoami` reports the URL users know. Without it,
+`whoami` omits the API URL rather than show the internal address. Behind TLS,
 list the public HTTPS origin explicitly: the server sees the proxy's HTTP connection and does
 not trust forwarded headers to establish the request origin.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@markmnl/fmsg-mcp",
   "mcpName": "io.github.markmnl/fmsg-mcp",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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": "0.2.2",
+  "version": "0.2.3",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@markmnl/fmsg-mcp",
-      "version": "0.2.2",
+      "version": "0.2.3",
       "transport": {
         "type": "stdio"
       },