@ardennguyen/zalo-agent-cli 2.5.9 → 3.0.0

package/src/mcp/mcp-config.js

@@ -5,7 +5,8 @@
 import { readFileSync, mkdirSync } from "fs";
 import { join } from "path";
 import { CONFIG_DIR } from "../core/credentials.js";
-import { writeFileAtomic } from "../utils/atomic-file.js";
+import { writeFileAtomic } from "../zalo/kernel/atomic-file.js";
+import { policyFor } from "../core/policy-layer.js";
 
 function mcpConfigFile() {
     return join(CONFIG_DIR, "mcp-config.json");
@@ -25,15 +26,30 @@ export function getDefaultConfig() {
             cooldown: "5m",
         },
         limits: {
-            maxMessagesPerPoll: 20,
             autoDigestThreshold: 50,
             bufferMaxAge: "2h",
             bufferMaxSize: 500,
         },
+        // Cached media (src/core/media-deliver.js, resolveMediaDelivery / resolveMediaLinkAuth in
+        // src/core/deploy-policy.js). Unset (null) keys take the defaults named beside them.
         media: {
             downloadDir: null, // unset -> the same per-account dir every other command uses
-            autoOpen: true,
+            // zalo_view_media opens the file with this machine's viewer: unset = true on stdio, false over HTTP.
+            autoOpen: null,
+            // Per kind: "inline" (MCP image/audio content), "link" (/zalo/media/<token>) or "tempfile" (a private
+            // decrypted copy). Unset: photo/gif/doodle/sticker/voice/audio inline, video/file link.
+            deliver: null,
+            inlineMaxBytes: null, // 5242880: larger media goes as a link
+            allowDeliver: null, // ["inline","link","tempfile"]: what a call (or the defaults) may pick
+            linkTtl: null, // "10m"
+            tempfileTtl: null, // "10m"
+            linkAuth: null, // "auto": "bearer" when publicUrl is another host, else "capability"
+            linkRateLimit: null, // 60 requests a minute per client address
+            capability: null, // {maxClients: 3, ttl: "15m"}: distinct client addresses a capability link serves
         },
+        // Reverse proxies whose X-Forwarded-For is believed (e.g. ["127.0.0.1"]). Unset (null) means
+        // ZALO_MCP_TRUSTED_PROXIES, else none: the client address is the socket's peer.
+        trustedProxies: null,
         tls: {
             cert: null,
             key: null,
@@ -41,18 +57,75 @@ export function getDefaultConfig() {
         oauth: {
             clientId: null,
             clientSecret: null,
-            issuerUrl: null,
+            issuerUrl: null, // deprecated name of publicUrl, still read
             clients: [],
         },
         webhookSecret: null,
         webhookBatchSize: 1, // events per webhook POST; 1 = each event alone, exactly as before the outbox
         webhookMaxAge: "24h", // an undelivered event older than this is dead-lettered, never silently dropped
-        groupConfirm: true, // zalo_group asks for confirm: true before leave / remove_member
+        // Who confirms a guarded action (src/core/confirm-guard.js): "agent", "human" or "off". Unset (null) means
+        // ZALO_MCP_CONFIRM_MODE, then the deprecated groupConfirm / ZALO_MCP_GROUP_CONFIRM, else "agent". It is not
+        // defaulted to "agent" here: a default would hide a file's own groupConfirm: false.
+        confirmMode: null,
+        // What agents see of the account's hidden chats (src/core/deploy-policy.js): "exclude", "contentless" or
+        // "include". Unset (null) means ZALO_MCP_HIDDEN_CHATS, else "exclude", as Zalo hides them until the PIN.
+        hiddenChats: null,
+        // Whether the hidden-chat tools take the PIN as an input. It puts the PIN in the MCP client's logs: for
+        // non-AI clients only. Unset (null) means ZALO_MCP_ALLOW_PIN_ARGUMENT, else false.
+        allowPinArgument: null,
+        // The one address people and clients reach this server at, behind a reverse proxy or TLS terminator
+        // (src/core/deploy-policy.js resolvePublicUrl): the MCP endpoint, the OAuth issuer, the one-time secure page
+        // and the QR login page. An https URL with an optional base path (http only for localhost). Unset (null) means
+        // --public-url / ZALO_MCP_PUBLIC_URL, then the deprecated oauth.issuerUrl, else the server's local address.
+        publicUrl: null,
+        // The one-time pages' delivery and the approve page's secret (src/core/approval.js). `secret`: "auto" (unset:
+        // the approver password when one is set and the link reaches the agent), "pin", "password" or "none";
+        // `deliver`: "result" (unset: the link is in the tool result), "webhook" (only to the webhook) or "both".
+        // Unset (null) means ZALO_MCP_APPROVAL_SECRET / ZALO_MCP_APPROVAL_DELIVER, else the defaults above.
+        approval: {
+            secret: null,
+            deliver: null,
+        },
+        // The admin API's own credential (src/core/admin-api.js; /zalo/admin/policy, /zalo/admin/usage), never the
+        // agent's. `tokenFile`: a file holding the admin token (a systemd credential, a KMS-decrypted mount); unset
+        // means ZALO_MCP_ADMIN_TOKEN_FILE, and `zalo-agent policy token --rotate` keeps one sealed in the key layer.
+        // `clientCa`: a CA whose client certificates are admitted (mTLS; needs --cert/--key). Read at start.
+        admin: {
+            tokenFile: null,
+            clientCa: null,
+        },
+        // On-demand presence (src/core/presence.js, resolved by src/core/presence-config.js): when the daemon holds the
+        // account's one socket. Unset (null) keys take the defaults named beside them; the runtime policy beats them.
+        presence: {
+            mode: null, // "on-demand" (backends) or "always-on"; stdio MCP and a stdout listener are always-on
+            idleTimeout: null, // "5m" with no demand before the socket parks (at least "30s")
+            minConnected: null, // "60s": never parks sooner after connecting
+            maxWakesPerHour: null, // 12: over it, the idle timeout doubles per wake (up to an hour)
+            warmWait: null, // "10s": how long a cache read waits for a waking socket
+            connectOnStart: null, // true: one catch-up at start, then park
+            catchUpEvery: null, // "off": a periodic catch-up while parked ("6h" etc.)
+            maxLeases: null, // 64 CRM leases per account
+            leaseTtl: null, // "90s" when a lease names none
+            leaseTtlMax: null, // "600s"
+            waitHoldsSocket: null, // true: a pending wait holds the socket (a tier may turn it off)
+            onKick: null, // "yield" (on-demand: let the account go until someone asks) or "exit" (code 3)
+        },
         httpPort: null,
         host: null,
     };
 }
 
+/** The media block of two layers: its per-kind `deliver` map and `capability` limits merge key by key. */
+function mergeMedia(base = {}, layer) {
+    if (!layer || typeof layer !== "object") return { ...base };
+    const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : null);
+    const out = { ...base, ...layer };
+    for (const key of ["deliver", "capability"]) {
+        if (obj(base?.[key]) && obj(layer[key])) out[key] = { ...base[key], ...layer[key] };
+    }
+    return out;
+}
+
 /**
  * Deep-merge an override layer over a base MCP config object.
  * @param {object} base
@@ -66,8 +139,11 @@ export function mergeMCPConfigLayer(base, layer) {
         ...layer,
         notify: { ...base.notify, ...(layer.notify || {}) },
         limits: { ...base.limits, ...(layer.limits || {}) },
-        media: { ...base.media, ...(layer.media || {}) },
+        media: mergeMedia(base.media, layer.media),
         tls: { ...base.tls, ...(layer.tls || {}) },
+        approval: { ...base.approval, ...(layer.approval || {}) },
+        admin: { ...base.admin, ...(layer.admin || {}) },
+        presence: { ...base.presence, ...(layer.presence || {}) },
         oauth: {
             ...base.oauth,
             ...(layer.oauth || {}),
@@ -214,7 +290,7 @@ export function saveMCPConfig(config) {
 
 /**
  * The webhook delivery settings of one account: `ZALO_WEBHOOK_BATCH_SIZE[_<ownId>]` and
- * `ZALO_WEBHOOK_MAX_AGE[_<ownId>]`, else `webhookBatchSize` / `webhookMaxAge` from the MCP config
+ * `ZALO_WEBHOOK_MAX_AGE[_<ownId>]` (under the live policy's `webhookBatchSize` / `webhookMaxAge`), else `webhookBatchSize` / `webhookMaxAge` from the MCP config
  * (`listen` has no config file and reads only the environment). A value that cannot be used falls
  * back to the default and is reported, so a typo is not mistaken for a working setting.
  *
@@ -223,11 +299,14 @@ export function saveMCPConfig(config) {
  * @param {NodeJS.ProcessEnv} [env]
  * @returns {{ batchSize: number, maxAgeMs: number, warnings: string[] }}
  */
-export function resolveWebhookDelivery(accountId, config = {}, env = process.env) {
+export function resolveWebhookDelivery(accountId, config = {}, env = process.env, policy = undefined) {
     const warnings = [];
     const defaults = getDefaultConfig();
+    // The live policy (src/core/policy-store.js) is above the environment.
+    const live = policy === undefined ? policyFor(accountId) : policy;
 
-    const rawBatch = envForAccount("ZALO_WEBHOOK_BATCH_SIZE", accountId, env) ?? config?.webhookBatchSize;
+    const rawBatch =
+        live?.webhookBatchSize ?? envForAccount("ZALO_WEBHOOK_BATCH_SIZE", accountId, env) ?? config?.webhookBatchSize;
     let batchSize = defaults.webhookBatchSize;
     if (rawBatch !== undefined && rawBatch !== null && rawBatch !== "") {
         const n = Number(rawBatch);
@@ -235,7 +314,8 @@ export function resolveWebhookDelivery(accountId, config = {}, env = process.env
         else warnings.push(`webhook batch size "${rawBatch}" is not a whole number from 1 to 100; using ${batchSize}`);
     }
 
-    const rawAge = envForAccount("ZALO_WEBHOOK_MAX_AGE", accountId, env) ?? config?.webhookMaxAge;
+    const rawAge =
+        live?.webhookMaxAge ?? envForAccount("ZALO_WEBHOOK_MAX_AGE", accountId, env) ?? config?.webhookMaxAge;
     let maxAgeMs = parseDuration(defaults.webhookMaxAge);
     if (rawAge !== undefined && rawAge !== null && rawAge !== "") {
         const ms = parseDuration(rawAge);
@@ -248,6 +328,28 @@ export function resolveWebhookDelivery(accountId, config = {}, env = process.env
     return { batchSize, maxAgeMs, warnings };
 }
 
+/**
+ * The webhook receiver of one account: the live policy's `webhook`, then the flag (`--webhook`), then
+ * `ZALO_WEBHOOK_URL[_<ownId>]`, then `webhook` in the MCP config; null for none.
+ *
+ * @param {object} args
+ * @param {string} args.accountId
+ * @param {string|null} [args.flag]
+ * @param {object} [args.config]
+ * @param {NodeJS.ProcessEnv} [args.env]
+ * @returns {string|null}
+ */
+export function resolveWebhookUrl({ accountId, flag = null, config = {}, env = process.env }) {
+    const live = policyFor(accountId)?.webhook;
+    return (
+        (typeof live === "string" && live.trim()) ||
+        flag?.trim() ||
+        envForAccount("ZALO_WEBHOOK_URL", accountId, env) ||
+        (typeof config?.webhook === "string" && config.webhook.trim()) ||
+        null
+    );
+}
+
 /**
  * Parse duration string (e.g. "2h", "5m", "30s") to milliseconds.
  * @param {string|number} duration

package/src/mcp/mcp-http-transport.js

@@ -13,6 +13,12 @@ import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
 import { newMcpServer } from "./new-server.js";
+import { maskSecurePath, SECURE_PATH_PREFIX } from "../core/secure-page.js";
+import { maskQrPath, QR_PATH_PREFIX } from "../utils/qr-http-server.js";
+import { maskMediaPath, MEDIA_PATH_PREFIX } from "../core/media-deliver.js";
+import { clientIpOf, handleMediaRequest, isLoopbackIp } from "../core/media-route.js";
+import { ADMIN_PATH_PREFIX } from "../core/admin-api.js";
+import { PRESENCE_PATH_PREFIX } from "../core/presence-leases.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -126,7 +132,9 @@ function verifyPkce(verifier, challenge, method = "S256") {
 }
 
 /**
- * Resolve the external origin (`https://host:port`) for OAuth metadata & `WWW-Authenticate` headers.
+ * Resolve the external origin (`https://host:port`) for OAuth metadata & `WWW-Authenticate` headers: `publicUrl`
+ * (with its deprecated names, resolvePublicUrl in src/core/deploy-policy.js) when set, else inferred from the request
+ * as 2.x always did. Only the OAuth metadata infers: the links to the one-time pages never use the Host header.
  * @param {import("express").Request} req
  * @param {string|null} configuredIssuer
  * @param {boolean} isTls
@@ -146,8 +154,14 @@ function resolveIssuerOrigin(req, configuredIssuer, isTls) {
 /**
  * Create HTTP or HTTPS MCP server with optional bearer token and OAuth 2.0 auth.
  * @param {Function} registerToolsFn - Registers tools on a McpServer instance
- * @param {object} deps - { api, buffer, filter, config, nameCache, accountDir, stageLock, syncJobs, health }
- *   (`health` is the daemon's ./core/daemon-health.js object: behind /health, /ready, /status and /metrics)
+ * @param {object} deps - { api, buffer, filter, config, nameCache, accountDir, stageLock, syncJobs, health,
+ *   securePage, qrPage, hiddenEvents }
+ *   (`health` is the daemon's ./core/daemon-health.js object: behind /health, /ready, /status and /metrics;
+ *   `securePage` serves the one-time input page at /zalo/secure/<token>, src/core/secure-page.js; `qrPage` the
+ *   one-time QR login page at /zalo/qr/<token>, src/utils/qr-http-server.js; `hiddenEvents`
+ *   applies the hiddenChats policy to /events/wait's messages; `presence` is the daemon's on-demand presence,
+ *   src/core/daemon-presence.js: every tool call and every /events/wait goes through it; `leases` its CRM lease
+ *   routes under /zalo/presence)
  * @param {number} port
  * @param {string|null} authToken - Bearer token (null = no auth unless oauth.clientSecret or oauth.clients is set)
  * @param {string} [host="127.0.0.1"] - Bind address
@@ -185,6 +199,26 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
     // Bounded dynamic client registrations (RFC 7591)
     const dynamicClients = new Map();
 
+    /**
+     * Whether a request carries this server's own credential: the --auth token, a configured client secret, or an
+     * OAuth access token it signed. Used by the auth middleware and by a bearer media link.
+     * @param {import("express").Request} req
+     * @returns {boolean}
+     */
+    const isAgentToken = (token) => {
+        if (!signingSecret || !token) return false;
+        if ((authToken && safeEqual(token, authToken)) || safeEqual(token, signingSecret)) return true;
+        for (const sec of configuredClients.values()) {
+            if (safeEqual(token, sec)) return true;
+        }
+        return Boolean(verifyOAuthToken(token, "zmcp_at_", signingSecret));
+    };
+    const isAuthorized = (req) => {
+        const authHeader = req.headers.authorization || "";
+        const token = /^bearer\s+/i.test(authHeader) ? authHeader.slice(7).trim() : "";
+        return isAgentToken(token);
+    };
+
     // CORS headers for browser-based MCP clients and OAuth discovery
     app.use((req, res, next) => {
         const remoteIp = req.socket?.remoteAddress || "";
@@ -196,7 +230,7 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
                 const ua = String(req.headers["user-agent"] || "-").slice(0, 80);
                 const h = String(req.headers.host || "-");
                 console.error(
-                    `${DEBUG_MARK}[mcp-http] ${req.method} ${req.originalUrl} -> ${res.statusCode} (host=${h} ip=${remoteIp} ua="${ua}")`,
+                    `${DEBUG_MARK}[mcp-http] ${req.method} ${maskMediaPath(maskQrPath(maskSecurePath(req.originalUrl)))} -> ${res.statusCode} (host=${h} ip=${remoteIp} ua="${ua}")`,
                 );
             });
         }
@@ -213,6 +247,77 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
         next();
     });
 
+    // The one-time secure input page (src/core/secure-page.js), before the body parsers and the bearer check: a
+    // person opens it in a browser with no token, and its own token in the path is what admits them. It reads its
+    // small form body itself.
+    if (deps.securePage) {
+        app.use(SECURE_PATH_PREFIX, (req, res, next) => {
+            req.url = `${SECURE_PATH_PREFIX}${req.url.replace(/^\//, "")}`;
+            deps.securePage
+                .handle(req, res)
+                .then((handled) => {
+                    if (!handled) next();
+                })
+                .catch(() => {
+                    if (!res.headersSent) res.status(500).set("Cache-Control", "no-store").end();
+                });
+        });
+    }
+
+    // The one-time QR login page, the same way: before the bearer check, admitted by its own token.
+    if (deps.qrPage) {
+        app.use(QR_PATH_PREFIX, (req, res, next) => {
+            req.url = `${QR_PATH_PREFIX}${req.url.replace(/^\//, "")}`;
+            deps.qrPage
+                .handle(req, res)
+                .then((handled) => {
+                    if (!handled) next();
+                })
+                .catch(() => {
+                    if (!res.headersSent) res.status(500).set("Cache-Control", "no-store").end();
+                });
+        });
+    }
+
+    // Media links (/zalo/media/<token>, src/core/media-route.js), before the bearer check as well: a capability link
+    // is admitted by its token, and a bearer link checks this server's own Authorization itself (isAuthorized).
+    if (deps.mediaLinks) {
+        app.use(MEDIA_PATH_PREFIX, (req, res, next) => {
+            req.url = `${MEDIA_PATH_PREFIX}${req.url.replace(/^\//, "")}`;
+            handleMediaRequest(req, res, {
+                links: deps.mediaLinks,
+                authorize: signingSecret ? isAuthorized : null,
+            })
+                .then((handled) => {
+                    if (!handled) next();
+                })
+                .catch(() => {
+                    if (!res.headersSent) res.status(500).set("Cache-Control", "no-store").end();
+                });
+        });
+    }
+
+    // The admin API (src/core/admin-api.js), before the bearer check too: it takes its own credential (an admin token
+    // or a client certificate) and refuses the agent's, so an agent can never change its own policy.
+    if (deps.admin) {
+        app.use(
+            ADMIN_PATH_PREFIX,
+            express.json({ limit: "64kb" }),
+            (req, res) => deps.admin.handle(req, res),
+            (err, req, res, _next) => {
+                res.status(err?.status || 400)
+                    .set("Cache-Control", "no-store")
+                    .json({
+                        error:
+                            err?.type === "entity.parse.failed"
+                                ? "the body is not valid JSON"
+                                : String(err?.message || err),
+                    });
+            },
+        );
+        deps.admin.isAgentToken = isAgentToken;
+    }
+
     app.use(express.json());
     app.use(express.urlencoded({ extended: false }));
 
@@ -511,20 +616,7 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
             const authHeader = req.headers.authorization || "";
             const token = /^bearer\s+/i.test(authHeader) ? authHeader.slice(7).trim() : "";
 
-            let matchesStaticToken =
-                Boolean(token) && ((authToken && safeEqual(token, authToken)) || safeEqual(token, signingSecret));
-            if (!matchesStaticToken && token) {
-                for (const sec of configuredClients.values()) {
-                    if (safeEqual(token, sec)) {
-                        matchesStaticToken = true;
-                        break;
-                    }
-                }
-            }
-            const oauthClaims =
-                !matchesStaticToken && token ? verifyOAuthToken(token, "zmcp_at_", signingSecret) : null;
-
-            if (!matchesStaticToken && !oauthClaims) {
+            if (!isAuthorized(req)) {
                 const origin = resolveIssuerOrigin(req, configuredIssuer, isTls);
                 const wwwAuth = token
                     ? `Bearer error="invalid_token", error_description="Unauthorized", resource_metadata="${origin}/.well-known/oauth-protected-resource/mcp"`
@@ -540,6 +632,12 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
     app.all("/mcp", async (req, res) => {
         try {
             const server = newMcpServer(pkg.version);
+            // This server lives for one request, so it cannot ask the person anything and hear back: the guard
+            // reads this and refuses confirmMode "human" at once instead of waiting (src/core/confirm-guard.js).
+            server.statelessHttp = true;
+            // Whether this request's client runs on this machine: only then can a tempfile path mean anything to it
+            // (src/core/media-deliver.js chooseDelivery). X-Forwarded-For counts only from a trusted proxy.
+            server.clientLoopback = isLoopbackIp(clientIpOf(req, deps.trustedProxies || []));
             registerToolsFn(
                 server,
                 deps.api,
@@ -550,6 +648,7 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
                 deps.accountDir,
                 deps.stageLock,
                 deps.syncJobs,
+                { presence: deps.presence ?? null },
             );
 
             const transport = new StreamableHTTPServerTransport({
@@ -575,6 +674,12 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
         }
     });
 
+    // CRM leases on the socket (src/core/presence-leases.js), behind the agent's bearer check above: a lease holds the
+    // socket, it cannot change the presence mode. `mcp start --http` passes `deps.leases` (its presence's routes).
+    if (deps.leases) {
+        app.use(PRESENCE_PATH_PREFIX, (req, res) => deps.leases.handle(req, res));
+    }
+
     // Long-poll endpoint for zero-CPU event-driven wakeup (protected by auth middleware above)
     app.get("/events/wait", async (req, res) => {
         const rawTimeout = Number(req.query.timeout);
@@ -589,6 +694,21 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
 
         const { limit, settleMs } = batchParams({ limit: req.query.limit, settleMs: req.query.settle });
 
+        // On-demand presence: a wait holds the socket while it waits (refused while yielded or signed out).
+        let ticket = null;
+        if (deps.presence) {
+            try {
+                ticket = await deps.presence.admit({ cls: "wait" });
+            } catch (e) {
+                if (!e?.code) throw e;
+                return res.status(409).json({
+                    error: e.message,
+                    code: e.code,
+                    ...(e.state ? { state: e.state } : {}),
+                });
+            }
+        }
+
         try {
             const { messages, hasMore } = await deps.buffer.waitForMessages({
                 threadId,
@@ -599,11 +719,22 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
                 settleMs,
             });
             if (res.writableEnded) return;
-            res.json(waitResult({ messages, hasMore, cursorWhenEmpty: deps.buffer.readCursor() }));
+            // Hidden chats by the deployment's policy; the cursor still moves past one left out.
+            const shown = deps.hiddenEvents ? deps.hiddenEvents(messages) : messages;
+            const skipped = Number(messages.at(-1)?._cursor) || 0;
+            res.json(
+                waitResult({
+                    messages: shown,
+                    hasMore,
+                    cursorWhenEmpty: Math.max(skipped, Number(deps.buffer.readCursor()) || 0),
+                }),
+            );
         } catch (err) {
             if (!res.headersSent) {
                 res.status(500).json({ error: err.message });
             }
+        } finally {
+            ticket?.release();
         }
     });
 
@@ -618,8 +749,9 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
         });
     });
 
-    // Readiness — no auth required: 200 only while the Zalo socket is connected, so a load balancer or a
-    // supervisor can stop sending work to a daemon whose account is offline.
+    // Readiness — no auth required: 200 while the Zalo socket is connected or parked idle (on-demand presence: the
+    // process serves, and wakes on demand), so a load balancer or a supervisor can stop sending work to a daemon whose
+    // account is offline.
     app.get("/ready", (req, res) => {
         const r = deps.health ? deps.health.ready() : { ready: true, socket: "unknown" };
         res.status(r.ready ? 200 : 503).json(r);
@@ -640,11 +772,16 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken, host =
     });
 
     if (isTls) {
-        const primary = https.createServer({ cert: tls.cert, key: tls.key }, app).listen(port, host, () => {
-            console.error(`MCP HTTPS server listening on ${host}:${port}`);
-        });
+        // A client CA (admin.clientCa) asks every client for a certificate without requiring one: only the admin API
+        // looks at it (req.socket.authorized), and every other route goes on as before.
+        const clientCa = tls.ca ? { ca: tls.ca, requestCert: true, rejectUnauthorized: false } : {};
+        const primary = https
+            .createServer({ cert: tls.cert, key: tls.key, ...clientCa }, app)
+            .listen(port, host, () => {
+                console.error(`MCP HTTPS server listening on ${host}:${port}`);
+            });
         if (port !== 0 && port !== 443) {
-            const tls443 = https.createServer({ cert: tls.cert, key: tls.key }, app);
+            const tls443 = https.createServer({ cert: tls.cert, key: tls.key, ...clientCa }, app);
             tls443.on("error", () => {
                 /* port 443 already in use or restricted — ignore */
             });

package/src/mcp/mcp-server.js

@@ -16,7 +16,7 @@ const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf8
 /**
  * Create and start MCP server with stdio transport.
  * All logs MUST use console.error() — stdout is reserved for MCP protocol.
- * @param {object} api - zca-js API instance
+ * @param {object} api - session object
  * @param {import("./message-buffer.js").MessageBuffer} buffer
  * @param {import("./thread-filter.js").ThreadFilter} filter
  * @param {object} config - MCP config
@@ -24,12 +24,23 @@ const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf8
  * @param {string} [accountDir] - account data dir, for cache reads and media paths
  * @param {object} [stageLock] - the daemon's one-stage-at-a-time lock (daemon-channel.js)
  * @param {object} [syncJobs] - account-local sync tracker shared by all MCP requests
+ * @param {{presence?: object|null}} [extras] - the daemon's presence (src/core/daemon-presence.js)
  * @returns {Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>}
  */
-export async function createMCPServer(api, buffer, filter, config, nameCache, accountDir, stageLock, syncJobs) {
+export async function createMCPServer(
+    api,
+    buffer,
+    filter,
+    config,
+    nameCache,
+    accountDir,
+    stageLock,
+    syncJobs,
+    extras = {},
+) {
     const server = newMcpServer(pkg.version);
 
-    registerTools(server, api, buffer, filter, config, nameCache, accountDir, stageLock, syncJobs);
+    registerTools(server, api, buffer, filter, config, nameCache, accountDir, stageLock, syncJobs, extras);
 
     const transport = new StdioServerTransport();
     await server.connect(transport);