@wirecat/cli-core 0.444.0 → 0.446.0

package/CHANGELOG.md

@@ -5,7 +5,30 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
-## Unreleased
+## 0.446.0 — 26.10.2026
+
+### Fixed
+
+- **`checkGuide` accepts a step that runs a group with an action of its own**, such as `mcp` now that it has
+  `mcp server`; before, it asked for one of the group's subcommands.
+- **The `mcp server` group states its effects** (reads locally), as a CLI that requires effects on every command
+  expects.
+
+## 0.445.0 — 26.10.2026
+
+### Added
+
+- **`mcp server start|stop|status` runs the HTTP MCP server in the background** (WireCat Desktop step 3). `start`
+  takes `--public-url`, `--port` and `--permission` as `mcp --http` does and answers once it listens; `stop` ends
+  only a server `start` started; `status --json` gives the port, the connector address, the login code for a new
+  browser app with when it runs out, and the apps logged in, by the name each gave itself. `mcp --http` now keeps a
+  lock beside its token file, so a second one for the same profile is refused. A CLI with its own `mcp` mounts
+  `mcpServerCommand` and passes `lockFile: httpLockFile(tokenFile)` to `serveOverHttp`.
+
+### Fixed
+
+- **The login code is renewed when it runs out**, not only when someone types a wrong or late one, and the login
+  page says it is shown in WireCat Desktop or the terminal.
 
 ## 0.444.0 — 26.10.2026
 

package/dist/cli/guide.js

@@ -291,7 +291,9 @@ export const checkStep = (program, run) => {
     const beforeDashes = rest.slice(index, rest.includes("--") ? rest.indexOf("--") : undefined);
     if (help && beforeDashes.some((word) => word === help.long || word === help.short))
         return [];
-    if (at.commands.length > 0)
+    // A group with an action of its own runs as typed: `mcp` serves, `mcp server start` is its child.
+    const runsItself = at._actionHandler != null;
+    if (at.commands.length > 0 && !runsItself)
         return [`needs one of: ${at.commands.map((one) => one.name()).join(", ")}`];
     for (const command of chain)
         silent(command);

package/dist/cli/index.d.ts

@@ -76,6 +76,7 @@ export { type HelpSection, inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, type InputPolicy, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";
 export { answerFields, checkJson, type EntityFields, entityFields, type JsonFieldsResolver, type JsonRequest, liftJson, } from "./json-fields.js";
 export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTerms, pagedList, pageOf, type QueryWords, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
+export { MCP_HTTP_DEFAULT_PORT, type McpServerOptions, type McpServerTarget, mcpServerCommand, } from "./mcp-server-command.js";
 export { formatMeetingBatch, prepareMeetingBatch } from "./meeting-batch.js";
 export { meetingEvidenceItem, meetingPersonContextItem } from "./meeting-evidence-answer.js";
 export { parseEvidenceFindingsJson, parseMeetingFindingsJson } from "./meeting-findings-input.js";

package/dist/cli/index.js

@@ -69,6 +69,7 @@ export { inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";
 export { answerFields, checkJson, entityFields, liftJson, } from "./json-fields.js";
 export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTerms, pagedList, pageOf, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";
+export { MCP_HTTP_DEFAULT_PORT, mcpServerCommand, } from "./mcp-server-command.js";
 export { formatMeetingBatch, prepareMeetingBatch } from "./meeting-batch.js";
 export { meetingEvidenceItem, meetingPersonContextItem } from "./meeting-evidence-answer.js";
 export { parseEvidenceFindingsJson, parseMeetingFindingsJson } from "./meeting-findings-input.js";

package/dist/cli/mcp-server-command.d.ts

@@ -0,0 +1,35 @@
+import { Command } from "commander";
+import { type ServerSystem } from "../background/system.js";
+export declare const MCP_HTTP_DEFAULT_PORT = 8765;
+/** What one CLI tells `mcp server` about the server it would run. */
+export interface McpServerTarget {
+    /** What a person types before `mcp`: `tg personal`, `memo`. */
+    invocation: string;
+    /** Absent for a CLI without profiles. */
+    profile?: string;
+    envPrefix: string;
+    env: NodeJS.ProcessEnv;
+    tokenFile: string;
+    /** The words after the CLI's own entry that run `mcp --http` in the foreground, before `--port`. */
+    argv: string[];
+    /** Added to the server's environment: the profile, for a CLI that reads it from there. */
+    childEnv?: Record<string, string>;
+    version: string;
+}
+export interface McpServerOptions {
+    /** How help shows the CLI before `mcp`: `tg personal`. */
+    example: string;
+    /** The CLI's own `mcp --http` default, when it is not 8765. */
+    defaultPort?: number;
+    target: (self: Command) => McpServerTarget;
+    /** The CLI's own answer: the item in `--json`, else the lines. */
+    answer: (self: Command, item: object, lines: string[]) => void;
+    system?: (self: Command) => ServerSystem | undefined;
+}
+/**
+ * `mcp --http` in the background: `start`, `stop`, `status`, as `server` does for `serve`. The server
+ * keeps a lock beside its token file (`state.ts`) with its port, address and login code, so status
+ * survives the shell that started it, and `stop` ends only a process that carries this CLI's marker.
+ * None of it is offered over MCP: status holds a live login code.
+ */
+export declare const mcpServerCommand: ({ example, defaultPort, target, answer, system, }: McpServerOptions) => Command;

package/dist/cli/mcp-server-command.js

@@ -0,0 +1,174 @@
+import { CliError } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { Command } from "commander";
+import { alive, carries } from "../background/processes.js";
+import { thisMachine } from "../background/system.js";
+import { readableLog, tail } from "../background/units.js";
+import { portOf, publicUrlOf } from "../http/public-url.js";
+import { httpLockFile, httpLogFile, mcpHttpMarker, readHttpLock, signedInClients, } from "../mcp/http/state.js";
+import { destroysNothing, LOCAL_READ, LOCAL_WRITE } from "./effects.js";
+export const MCP_HTTP_DEFAULT_PORT = 8765;
+const LOOKS = 120;
+const clock = (iso) => {
+    const when = new Date(iso);
+    const time = when.toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit" });
+    return when.toDateString() === new Date().toDateString() ? time : `${when.toLocaleDateString("sv-SE")} ${time}`;
+};
+const connectorUrl = (lock) => new URL("/mcp", lock.publicUrl).href;
+const liveCode = (lock, now) => lock.loginCode && lock.loginCodeExpiresAt && Date.parse(lock.loginCodeExpiresAt) > now
+    ? { code: lock.loginCode, expires_at: lock.loginCodeExpiresAt }
+    : null;
+const markerOf = (target) => `${mcpHttpMarker(target.envPrefix)}=${target.profile ?? "default"}`;
+/** Who started it decides whether `stop` may end it: only a process that carries our marker. */
+const byOf = (target, pid) => (carries(pid, markerOf(target)) ? "server" : "hand");
+const serving = (target, lock, now) => ({
+    pid: lock.pid,
+    started_at: lock.startedAt,
+    listening: lock.listeningAt !== undefined,
+    by: byOf(target, lock.pid),
+    port: lock.port,
+    public_url: lock.publicUrl,
+    connector_url: connectorUrl(lock),
+    login_code: liveCode(lock, now),
+    ...(lock.version ? { version: lock.version, outdated: lock.version !== target.version } : {}),
+});
+const clientLines = (clients) => clients.length === 0
+    ? ["No browser app is logged in."]
+    : [
+        `Logged-in apps (names are what each app calls itself): ${clients
+            .map((one) => `${one.claimedName === null ? "no name" : JSON.stringify(one.claimedName)} (${clock(one.lastLoginAt)})`)
+            .join(", ")}.`,
+    ];
+/**
+ * `mcp --http` in the background: `start`, `stop`, `status`, as `server` does for `serve`. The server
+ * keeps a lock beside its token file (`state.ts`) with its port, address and login code, so status
+ * survives the shell that started it, and `stop` ends only a process that carries this CLI's marker.
+ * None of it is offered over MCP: status holds a live login code.
+ */
+export const mcpServerCommand = ({ example, defaultPort = MCP_HTTP_DEFAULT_PORT, target, answer, system, }) => {
+    const command = annotate(new Command("server"), { effects: LOCAL_READ, mcp: false })
+        .summary("run the HTTP MCP server in the background")
+        .description("start, stop and check `mcp --http` in the background; status shows the login code for a browser app");
+    const machine = (self) => system?.(self) ?? thisMachine();
+    destroysNothing(annotate(command.command("start"), {
+        effects: LOCAL_WRITE,
+        mcp: false,
+        examples: [`${example} mcp server start --public-url https://laptop.example.ts.net`],
+    }))
+        .summary("start the HTTP MCP server in the background")
+        .description("start `mcp --http` apart from this shell and answer once it listens, with its login code")
+        .option("--port <port>", `the local port (default ${defaultPort})`)
+        .option("--public-url <url>", "the tunnel's https address the browser apps use, e.g. https://<name>.ts.net")
+        .option("--permission <key=level>", "make a permission stricter for this server only; repeat for more keys", (value, previous = []) => [...previous, value])
+        .action(async function () {
+        // A CLI whose `mcp` takes the same flags reads them first, so they are looked up on both.
+        const flags = this.optsWithGlobals();
+        const one = target(this);
+        const url = publicUrlOf(flags.publicUrl, { missing: "mcp server start", reaches: "the browser apps reach it" });
+        const port = portOf(flags.port, defaultPort);
+        const lockFile = httpLockFile(one.tokenFile);
+        const before = readHttpLock(lockFile);
+        if (before && alive(before.pid)) {
+            answer(this, { profile: one.profile ?? null, started: false, running: true, ...serving(one, before, Date.now()) }, [
+                `Already serving ${one.invocation} over HTTP since ${clock(before.startedAt)} (PID ${before.pid}, port ${before.port}).`,
+            ]);
+            return;
+        }
+        const sys = machine(this);
+        const log = httpLogFile(one.tokenFile);
+        const { [`${one.envPrefix}_TIMEOUT`]: _timeout, ...inherited } = one.env;
+        const pid = sys.spawn([
+            ...one.argv,
+            "--port",
+            String(port),
+            "--public-url",
+            url.origin,
+            ...(flags.permission ?? []).flatMap((entry) => ["--permission", entry]),
+        ], { ...inherited, ...one.childEnv, [mcpHttpMarker(one.envPrefix)]: one.profile ?? "default" }, log);
+        for (let look = 0; look < LOOKS; look++) {
+            const now = readHttpLock(lockFile);
+            if (now?.pid === pid && now.listeningAt) {
+                const code = liveCode(now, Date.now());
+                answer(this, { profile: one.profile ?? null, started: true, running: true, ...serving(one, now, Date.now()), log }, [
+                    `Started: serving ${one.invocation} over HTTP (PID ${pid}) on 127.0.0.1:${now.port}.`,
+                    `Browser apps connect to ${connectorUrl(now)}`,
+                    ...(code ? [`Login code for a new browser app: ${code.code} (until ${clock(code.expires_at)}).`] : []),
+                ]);
+                return;
+            }
+            if (!alive(pid)) {
+                const last = readableLog(tail(log, 5)).trim();
+                throw new CliError("provider_unavailable", `mcp --http stopped before it listened${last ? `:\n${last}` : ""}`);
+            }
+            await sys.pause();
+        }
+        throw new CliError("timeout", `mcp --http is running but not listening yet — \`${one.invocation} mcp server status\`; its log: ${log}`);
+    });
+    destroysNothing(annotate(command.command("stop"), { effects: LOCAL_WRITE, mcp: false, examples: [`${example} mcp server stop`] }))
+        .summary("stop the background HTTP MCP server")
+        .description("stop `mcp --http` — only one that `mcp server start` started")
+        .action(async function () {
+        const one = target(this);
+        const lock = readHttpLock(httpLockFile(one.tokenFile));
+        if (!lock || !alive(lock.pid)) {
+            answer(this, { profile: one.profile ?? null, stopped: false }, [
+                `Nothing to stop: ${one.invocation} is not serving MCP over HTTP.`,
+            ]);
+            return;
+        }
+        if (byOf(one, lock.pid) !== "server") {
+            throw new CliError("validation_error", `mcp --http for ${one.invocation} (PID ${lock.pid}) was not started by \`${one.invocation} mcp server start\` — stop it where it runs`);
+        }
+        process.kill(lock.pid, "SIGTERM");
+        const sys = machine(this);
+        for (let look = 0; look < LOOKS && alive(lock.pid); look++)
+            await sys.pause();
+        if (alive(lock.pid))
+            throw new CliError("timeout", `mcp --http (PID ${lock.pid}) has not stopped yet`);
+        answer(this, { profile: one.profile ?? null, stopped: true, pid: lock.pid }, [
+            `Stopped serving ${one.invocation} over HTTP (PID ${lock.pid}).`,
+        ]);
+    });
+    annotate(command.command("status"), {
+        effects: LOCAL_READ,
+        mcp: false,
+        examples: [`${example} mcp server status --json`],
+    })
+        .summary("whether the HTTP MCP server runs, its login code and the apps logged in")
+        .description("whether `mcp --http` runs, on which port and address, the login code for a new browser app, and the apps logged in")
+        .action(function () {
+        const one = target(this);
+        const lock = readHttpLock(httpLockFile(one.tokenFile));
+        const now = Date.now();
+        const running = lock !== undefined && alive(lock.pid);
+        const clients = signedInClients(one.tokenFile, now);
+        const live = running ? serving(one, lock, now) : undefined;
+        answer(this, {
+            profile: one.profile ?? null,
+            running,
+            ...(live ?? {}),
+            ...(lock && !running ? { stale: { pid: lock.pid, started_at: lock.startedAt } } : {}),
+            clients: clients.map((client) => ({
+                claimed_name: client.claimedName,
+                last_login_at: client.lastLoginAt,
+            })),
+            log: httpLogFile(one.tokenFile),
+        }, [
+            live && lock
+                ? `Serving ${one.invocation} over HTTP since ${clock(lock.startedAt)} (PID ${lock.pid}) on port ${lock.port}${live.listening ? "" : ", not listening yet"}; browser apps connect to ${live.connector_url}. ${live.by === "server" ? `Started by \`${one.invocation} mcp server start\`.` : "Started by hand — `mcp server stop` leaves it alone."}`
+                : `Not serving ${one.invocation} over HTTP.`,
+            ...(live?.login_code
+                ? [
+                    `Login code for a new browser app: ${live.login_code.code} (until ${clock(live.login_code.expires_at)}).`,
+                ]
+                : []),
+            ...(lock && !running
+                ? [
+                    `A server that started ${clock(lock.startedAt)} (PID ${lock.pid}) is gone; the next start takes its place.`,
+                ]
+                : []),
+            ...clientLines(clients),
+        ]);
+    });
+    return command;
+};

package/dist/cli/messenger/mcp-command.d.ts

@@ -1,5 +1,6 @@
 import { type ChildProcessWithoutNullStreams } from "node:child_process";
 import { Command } from "commander";
+import type { ServerSystem } from "../../background/system.js";
 import { type AppIdentity } from "../../ports/app.js";
 import { type BaseEnvironment } from "../context.js";
 import { type Messenger } from "./context.js";
@@ -9,6 +10,7 @@ export interface McpEnvironment extends BaseEnvironment {
         scriptPath?: string;
         execPath?: string;
     };
+    system?: ServerSystem;
 }
 export interface McpFlags {
     permission?: string[];

package/dist/cli/messenger/mcp-command.js

@@ -7,15 +7,17 @@ import { installerOf } from "@wirecat/cli-base/update";
 import { Command } from "commander";
 import { ATTACHMENT_LIMIT_ENV } from "../../attachments/limits.js";
 import { portOf, publicUrlOf } from "../../http/public-url.js";
+import { httpLockFile } from "../../mcp/http/state.js";
 import { envName } from "../../ports/app.js";
 import { environmentOf } from "../context.js";
 import { grantsAuthority, LOCAL_READ, LOCAL_WRITE, REMOTE_WRITE } from "../effects.js";
 import { itemOf, renderAnswer } from "../envelope.js";
+import { MCP_HTTP_DEFAULT_PORT, mcpServerCommand } from "../mcp-server-command.js";
 import { rootOf } from "../profile.js";
 import { nextStep } from "../steps.js";
 import { recalledAccount } from "./accounts.js";
 import { messengerContext } from "./context.js";
-const DEFAULT_PORT = 8765;
+const DEFAULT_PORT = MCP_HTTP_DEFAULT_PORT;
 /** Where `mcp --http` keeps the hashes of the tokens it issued — per profile, in the state folder. */
 export const httpTokenFile = (app, profile, env) => join(resolvePaths({ appName: app.appName, prefix: app.envPrefix, env }).state, "mcp-http", `${profile}.json`);
 const withFlags = (command) => command.option("--permission <key=level>", "make a permission stricter for this server only, like messages.send=deny; it never loosens the profile; repeat for more keys", (value, previous = []) => [...previous, value]);
@@ -43,10 +45,13 @@ export const mcpCommand = (messenger) => {
                 reaches: `the browser apps reach ${app.command}`,
             });
             const { serveOverHttpUntilStopped } = await import("../../mcp/server.js");
+            const tokenFile = httpTokenFile(app, context.settings.profile, context.env);
             await serveOverHttpUntilStopped(this, context, messenger, {}, {
                 publicUrl,
                 port: portOf(flags.port, DEFAULT_PORT),
-                tokenFile: httpTokenFile(app, context.settings.profile, context.env),
+                tokenFile,
+                lockFile: httpLockFile(tokenFile),
+                version: app.version,
             });
             return;
         }
@@ -54,6 +59,24 @@ export const mcpCommand = (messenger) => {
         const { serveOverStdio } = await import("../../mcp/server.js");
         await serveOverStdio(this, context, messenger, {});
     });
+    command.addCommand(mcpServerCommand({
+        example: `${app.command} personal`,
+        target: (self) => {
+            const { settings, env } = messengerContext(self, messenger);
+            return {
+                invocation: `${app.command} ${settings.profile}`,
+                profile: settings.profile,
+                envPrefix: app.envPrefix,
+                env,
+                tokenFile: httpTokenFile(app, settings.profile, env),
+                argv: ["mcp", "--http"],
+                childEnv: { [`${app.envPrefix}_PROFILE`]: settings.profile },
+                version: app.version,
+            };
+        },
+        answer: (self, item, lines) => renderAnswer(self, messengerContext(self, messenger), itemOf(item), () => lines.join("\n")),
+        system: (self) => environmentOf(self).system,
+    }));
     command.addCommand(withFlags(annotate(new Command("config"), {
         effects: LOCAL_READ,
         examples: [`${app.command} personal mcp config`],

package/dist/mcp/http/oauth.d.ts

@@ -7,6 +7,7 @@ export interface OwnerLogin {
     verifier: OAuthTokenVerifier;
     /** Answers the login routes; `undefined` for any other path. */
     handle(request: Request): Promise<Response | undefined>;
+    close(): void;
 }
 /**
  * An OAuth 2.1 authorization server for exactly one owner (CLI-58). Anyone may register a client —
@@ -18,7 +19,7 @@ export declare const ownerLogin: ({ issuer, resource, file, appName, onCode, now
     resource: URL;
     file: string;
     appName: string;
-    /** Shown to the owner on stderr: the code for the next login. */
+    /** The code for the next login, for the owner's eyes only: their terminal, or the server's status file. */
     onCode: (code: string, expires: Date) => void;
     now?: () => number;
 }) => OwnerLogin;

package/dist/mcp/http/oauth.js

@@ -1,9 +1,8 @@
 import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { OAuthError, OAuthErrorCode, } from "@modelcontextprotocol/server";
-const ACCESS_SECONDS = 60 * 60;
-const REFRESH_SECONDS = 30 * 24 * 60 * 60;
+import { ACCESS_SECONDS, REFRESH_SECONDS, readStored } from "./state.js";
 const AUTH_CODE_MS = 60 * 1000;
 const LOGIN_CODE_MS = 10 * 60 * 1000;
 const WRONG_TRIES = 5;
@@ -20,7 +19,7 @@ const same = (given, expected) => {
 };
 /** Only hashes reach the disk: the file is worth nothing to someone who copies it. */
 const tokenFile = (path) => ({
-    read: () => existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : { clients: [], tokens: [] },
+    read: () => readStored(path),
     write: (stored) => {
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
         const temporary = `${path}.${randomBytes(16).toString("hex")}.tmp`;
@@ -58,9 +57,14 @@ export const ownerLogin = ({ issuer, resource, file, appName, onCode, now = () =
     let login = { value: "", expires: 0 };
     let wrong = 0;
     let retryAt = 0;
+    let renewal;
+    // Renewed when it runs out, not only when someone tries it: a code read from the status file must still work.
     const freshCode = () => {
         const part = () => Array.from({ length: 4 }, () => CODE_ALPHABET[randomInt(CODE_ALPHABET.length)]).join("");
         login = { value: `${part()}-${part()}`, expires: now() + LOGIN_CODE_MS };
+        clearTimeout(renewal);
+        renewal = setTimeout(freshCode, LOGIN_CODE_MS);
+        renewal.unref();
         onCode(login.value, new Date(login.expires));
     };
     freshCode();
@@ -147,7 +151,7 @@ export const ownerLogin = ({ issuer, resource, file, appName, onCode, now = () =
             .join("");
         const who = escapeHtml(client.name ?? "an application");
         const target = new URL(params.get("redirect_uri") ?? "");
-        const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapeHtml(appName)} login</title><style>body{font:16px system-ui,sans-serif;max-width:28rem;margin:3rem auto;padding:0 1rem;color:#1d2430}input[type=text]{font:20px ui-monospace,monospace;letter-spacing:.1em;width:100%;padding:.5rem;margin:.5rem 0 1rem;box-sizing:border-box}button{font:inherit;padding:.5rem 1rem}.error{color:#b42318}</style></head><body><h1>${escapeHtml(appName)}</h1><p>An app that calls itself <strong>${who}</strong> asks to reach your messages through <code>${escapeHtml(appName)} mcp --http</code>.</p><p>After you allow it, the login goes to <strong>${escapeHtml(target.host)}</strong>. Allow only if that is the app you are connecting, such as chatgpt.com or claude.ai.</p><p>Type the code shown in the terminal where it runs. If you did not start this login, close this page.</p>${message ? `<p class="error">${escapeHtml(message)}</p>` : ""}<form method="post" action="/authorize">${hidden}<label>Code from the terminal<input type="text" name="login_code" autocomplete="off" autofocus required></label><button type="submit">Allow</button></form></body></html>`;
+        const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapeHtml(appName)} login</title><style>body{font:16px system-ui,sans-serif;max-width:28rem;margin:3rem auto;padding:0 1rem;color:#1d2430}input[type=text]{font:20px ui-monospace,monospace;letter-spacing:.1em;width:100%;padding:.5rem;margin:.5rem 0 1rem;box-sizing:border-box}button{font:inherit;padding:.5rem 1rem}.error{color:#b42318}</style></head><body><h1>${escapeHtml(appName)}</h1><p>An app that calls itself <strong>${who}</strong> asks to reach your messages through <code>${escapeHtml(appName)} mcp --http</code>.</p><p>After you allow it, the login goes to <strong>${escapeHtml(target.host)}</strong>. Allow only if that is the app you are connecting, such as chatgpt.com or claude.ai.</p><p>Type the code shown in WireCat Desktop, or in the terminal where the server runs. If you did not start this login, close this page.</p>${message ? `<p class="error">${escapeHtml(message)}</p>` : ""}<form method="post" action="/authorize">${hidden}<label>Login code<input type="text" name="login_code" autocomplete="off" autofocus required></label><button type="submit">Allow</button></form></body></html>`;
         return new Response(html, {
             status: message ? 400 : 200,
             headers: {
@@ -174,7 +178,7 @@ export const ownerLogin = ({ issuer, resource, file, appName, onCode, now = () =
             return new Response("This server needs response_type=code and PKCE with S256.", { status: 400 });
         if (request.method !== "POST")
             return page(params, client);
-        const throttled = () => new Response("Too many wrong codes. Wait before trying the new terminal code.", {
+        const throttled = () => new Response("Too many wrong codes. Wait, then try the new code.", {
             status: 429,
             headers: { "retry-after": String(Math.ceil((retryAt - now()) / 1000)) },
         });
@@ -187,7 +191,7 @@ export const ownerLogin = ({ issuer, resource, file, appName, onCode, now = () =
         const typed = (params.get("login_code") ?? "").trim().toUpperCase();
         if (login.expires < now()) {
             freshCode();
-            return page(params, client, "The code expired. A new one is shown in the terminal.");
+            return page(params, client, "The code expired. A new one is shown in WireCat Desktop and in the terminal.");
         }
         if (!same(typed, login.value)) {
             wrong += 1;
@@ -266,6 +270,7 @@ export const ownerLogin = ({ issuer, resource, file, appName, onCode, now = () =
     };
     return {
         code: () => login.value,
+        close: () => clearTimeout(renewal),
         metadata,
         verifier,
         handle: async (request) => {

package/dist/mcp/http/serve.d.ts

@@ -11,6 +11,12 @@ export interface HttpOptions {
     onCode: (code: string, expires: Date) => void;
     onError?: (error: Error) => void;
     now?: () => number;
+    /**
+     * `httpLockFile(tokenFile)`: one server per token file, and what `mcp server status` reads — the
+     * port, the address and the current login code. Without it nothing is written.
+     */
+    lockFile?: string;
+    version?: string;
 }
 /**
  * MCP over Streamable HTTP on 127.0.0.1, behind the owner's tunnel (CLI-58). Every MCP request needs

package/dist/mcp/http/serve.js

@@ -1,7 +1,9 @@
 import { randomUUID } from "node:crypto";
 import { createMcpHandler, getOAuthProtectedResourceMetadataUrl, hostHeaderValidationResponse, isLegacyRequest, oauthMetadataResponse, requireBearerAuth, WebStandardStreamableHTTPServerTransport, } from "@modelcontextprotocol/server";
+import { CliError } from "@wirecat/cli-base";
 import { listen } from "../../http/listen.js";
 import { ownerLogin } from "./oauth.js";
+import { httpLock } from "./state.js";
 export const MCP_PATH = "/mcp";
 const LOCAL = ["localhost", "127.0.0.1"];
 const MAX_SESSIONS = 20;
@@ -65,10 +67,31 @@ const legacySessions = (build, now) => {
  * the owner's browser cannot reach the port through a rebound DNS name.
  */
 export const serveOverHttp = async (build, options) => {
-    const { publicUrl, port, tokenFile, appName, onCode, onError, now } = options;
+    const { publicUrl, port, tokenFile, appName, onCode, onError, now, lockFile, version } = options;
+    const lock = lockFile
+        ? httpLock(lockFile, {
+            pid: process.pid,
+            startedAt: new Date().toISOString(),
+            port,
+            publicUrl: publicUrl.href,
+            ...(version ? { version } : {}),
+        })
+        : undefined;
+    if (lock?.held)
+        throw new CliError("validation_error", `${appName} already serves MCP over HTTP for this profile on port ${lock.held.port} (PID ${lock.held.pid}, since ${lock.held.startedAt})`);
     const issuer = new URL(publicUrl.origin);
     const resource = new URL(MCP_PATH, issuer);
-    const login = ownerLogin({ issuer, resource, file: tokenFile, appName, onCode, ...(now ? { now } : {}) });
+    const login = ownerLogin({
+        issuer,
+        resource,
+        file: tokenFile,
+        appName,
+        onCode: (code, expires) => {
+            lock?.update({ loginCode: code, loginCodeExpiresAt: expires.toISOString() });
+            onCode(code, expires);
+        },
+        ...(now ? { now } : {}),
+    });
     const insecure = issuer.protocol === "http:" && LOCAL.includes(issuer.hostname);
     const mcp = createMcpHandler(build, { legacy: "reject", ...(onError ? { onerror: onError } : {}) });
     const legacy = legacySessions(build, now ?? Date.now);
@@ -106,13 +129,24 @@ export const serveOverHttp = async (build, options) => {
         if (auth instanceof Response)
             return auth;
         return (await isLegacyRequest(request)) ? legacy.handle(request, auth) : mcp.fetch(request, { authInfo: auth });
-    }, { host: "127.0.0.1", port });
+    }, { host: "127.0.0.1", port }).catch((error) => {
+        login.close();
+        lock?.release();
+        throw error;
+    });
+    lock?.update({ listeningAt: new Date().toISOString() });
     return {
         url: listening.url,
         close: async () => {
-            await listening.close();
-            await legacy.close();
-            await mcp.close();
+            login.close();
+            try {
+                await listening.close();
+                await legacy.close();
+                await mcp.close();
+            }
+            finally {
+                lock?.release();
+            }
         },
     };
 };

package/dist/mcp/http/state.d.ts

@@ -0,0 +1,52 @@
+import { type Lock } from "../../background/lock.js";
+export declare const ACCESS_SECONDS: number;
+export declare const REFRESH_SECONDS: number;
+export interface StoredClient {
+    id: string;
+    name?: string;
+    secretHash?: string;
+    redirectUris: string[];
+    authMethod: "none" | "client_secret_post" | "client_secret_basic";
+    issuedAt: number;
+}
+export interface StoredToken {
+    hash: string;
+    kind: "access" | "refresh";
+    clientId: string;
+    expiresAt: number;
+}
+/** The token file: registered clients and the hashes of the tokens they hold. */
+export interface Stored {
+    clients: StoredClient[];
+    tokens: StoredToken[];
+}
+export declare const readStored: (path: string) => Stored;
+/** What a running `mcp --http` writes beside its token file, mode 600 — the login code is a live credential. */
+export interface HttpLock extends Lock {
+    port: number;
+    publicUrl: string;
+    loginCode?: string;
+    loginCodeExpiresAt?: string;
+}
+/** The variable a server started by `mcp server start` carries; a serve's `<PREFIX>_SERVER` never ends with it. */
+export declare const mcpHttpMarker: (envPrefix: string) => string;
+export declare const httpLogFile: (tokenFile: string) => string;
+/** Beside the token file, so each CLI's own layout decides both: `mcp-http/<profile>.json` → `.lock`. */
+export declare const httpLockFile: (tokenFile: string) => string;
+export declare const readHttpLock: (path: string) => HttpLock | undefined;
+/** The lock a serving process keeps current: taken before it listens, given up when it closes. */
+export declare const httpLock: (path: string, first: HttpLock) => {
+    held: HttpLock | undefined;
+    update: (change: Partial<HttpLock>) => void;
+    release: () => void;
+};
+export interface SignedInClient {
+    /** What the app said its name was when it registered — anyone may register, so it proves nothing. */
+    claimedName: string | null;
+    lastLoginAt: string;
+}
+/**
+ * The apps that hold a token now, and when each last got one. Ids and hashes stay in the file: what
+ * leaves is enough to recognise an app, never to act as it.
+ */
+export declare const signedInClients: (tokenFile: string, now?: number) => SignedInClient[];

package/dist/mcp/http/state.js

@@ -0,0 +1,49 @@
+import { existsSync, readFileSync } from "node:fs";
+import { holdLock, readLock, releaseLock, takeLock } from "../../background/lock.js";
+export const ACCESS_SECONDS = 60 * 60;
+export const REFRESH_SECONDS = 30 * 24 * 60 * 60;
+export const readStored = (path) => existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : { clients: [], tokens: [] };
+/** The variable a server started by `mcp server start` carries; a serve's `<PREFIX>_SERVER` never ends with it. */
+export const mcpHttpMarker = (envPrefix) => `${envPrefix}_MCP_HTTP`;
+export const httpLogFile = (tokenFile) => `${tokenFile.replace(/\.json$/, "")}.log`;
+/** Beside the token file, so each CLI's own layout decides both: `mcp-http/<profile>.json` → `.lock`. */
+export const httpLockFile = (tokenFile) => `${tokenFile.replace(/\.json$/, "")}.lock`;
+export const readHttpLock = (path) => {
+    const lock = readLock(path);
+    return lock && typeof lock.port === "number" && typeof lock.publicUrl === "string" ? lock : undefined;
+};
+/** The lock a serving process keeps current: taken before it listens, given up when it closes. */
+export const httpLock = (path, first) => {
+    let current = first;
+    const held = takeLock(path, current);
+    return {
+        held: held,
+        update: (change) => {
+            current = { ...current, ...change };
+            holdLock(path, current);
+        },
+        release: () => releaseLock(path),
+    };
+};
+/**
+ * The apps that hold a token now, and when each last got one. Ids and hashes stay in the file: what
+ * leaves is enough to recognise an app, never to act as it.
+ */
+export const signedInClients = (tokenFile, now = Date.now()) => {
+    const seconds = Math.floor(now / 1000);
+    const { clients, tokens } = readStored(tokenFile);
+    const last = new Map();
+    for (const token of tokens) {
+        if (token.expiresAt <= seconds)
+            continue;
+        const issued = token.expiresAt - (token.kind === "access" ? ACCESS_SECONDS : REFRESH_SECONDS);
+        last.set(token.clientId, Math.max(last.get(token.clientId) ?? 0, issued));
+    }
+    return clients
+        .filter((client) => last.has(client.id))
+        .map((client) => ({
+        claimedName: client.name ?? null,
+        lastLoginAt: new Date((last.get(client.id) ?? 0) * 1000).toISOString(),
+    }))
+        .sort((a, b) => b.lastLoginAt.localeCompare(a.lastLoginAt));
+};

package/dist/mcp/index.d.ts

@@ -3,4 +3,5 @@ export { type AgentAnswer, type AgentContext, type AgentProgram, type AgentTool,
 export { type BotServerOptions, createBotServer, type RunBotCommand } from "./bot/server.js";
 export { revokeAll } from "./http/oauth.js";
 export { type HttpOptions, MCP_PATH, serveOverHttp } from "./http/serve.js";
+export { httpLockFile } from "./http/state.js";
 export { type McpCommand, registerCommands } from "./surface.js";

package/dist/mcp/index.js

@@ -4,4 +4,5 @@ export { runCommandForAgent, toolsFromCommands, } from "./agent.js";
 export { createBotServer } from "./bot/server.js";
 export { revokeAll } from "./http/oauth.js";
 export { MCP_PATH, serveOverHttp } from "./http/serve.js";
+export { httpLockFile } from "./http/state.js";
 export { registerCommands } from "./surface.js";

package/dist/mcp/server.js

@@ -25,6 +25,7 @@ import { levelFor, readKeysForCommand } from "../sends/permissions.js";
 import { openStore } from "../store/store.js";
 import { runCommandForAgent, toolsFromCommands } from "./agent.js";
 import { agentLog } from "./agent-log.js";
+import { mcpHttpMarker } from "./http/state.js";
 import { instructions } from "./instructions.js";
 import { registerPrompts } from "./prompts.js";
 import { registerResources } from "./resources.js";
@@ -469,10 +470,14 @@ export const serveOverHttpUntilStopped = async (command, context, messenger, opt
     const { session, embedders, build, log } = createServer(command, context, messenger, options);
     const { serveOverHttp } = await import("./http/serve.js");
     const appName = messenger.app.command;
+    const appEnvPrefix = messenger.app.envPrefix;
     const listening = await serveOverHttp(build, {
         ...http,
         appName,
-        onCode: (code, expires) => context.renderer.note(`login code for a new browser app: ${code} (until ${expires.toTimeString().slice(0, 5)}; a new one after each login)`),
+        // In the background its log is a file; the code goes only to the lock that `mcp server status` reads.
+        onCode: (code, expires) => context.renderer.note(context.env[mcpHttpMarker(appEnvPrefix)] === undefined
+            ? `login code for a new browser app: ${code} (until ${expires.toTimeString().slice(0, 5)}; a new one after each login)`
+            : `a new login code for a browser app: \`${appName} ${context.settings.profile} mcp server status\``),
         onError: (error) => context.renderer.note(`mcp: ${error.message}`),
     }).catch(async (error) => {
         await session.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.444.0",
+  "version": "0.446.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",

package/parity.json

@@ -3179,6 +3179,23 @@
         }
       }
     },
+    "mcp server": {
+      "in": "all"
+    },
+    "mcp server start": {
+      "in": "all",
+      "options": {
+        "--permission": "all",
+        "--port": "all",
+        "--public-url": "all"
+      }
+    },
+    "mcp server status": {
+      "in": "all"
+    },
+    "mcp server stop": {
+      "in": "all"
+    },
     "mentions": {
       "in": "all"
     },