@wirecat/cli-core 0.470.0 → 0.471.0

package/CHANGELOG.md

@@ -7,6 +7,31 @@ shape of this file.
 
 ## Unreleased
 
+## 0.471.0 — 27.10.2026
+
+### Added
+
+- **`appMcpCommand(app, configuration, { name, untrusted, permissionExample, skill?, signedIn? })` — the shared
+  `mcp` for a CLI that is not a messenger** (gcal, drive and zoom each had their own): `mcp serve | revoke | server
+  start|stop|status | config | add | check`, the same commands, flags and answers as a messenger's `mcpCommand`,
+  with `--profiles <names|all>` (no profile is ever picked), `--http`, `--port`, `--public-url` and `--permission`
+  (a key no command checks is refused). Every command of the program is a tool behind `<cli>_tools_search`,
+  `<cli>_read` and `<cli>_write`, run in this process through the CLI's own `run`, under the profile's permissions
+  and its `configuration.permissions` keys; `mcp` itself is left out. The instructions come from the new
+  `appInstructions`, which requires the kinds of text other people wrote (`untrusted`, WC-MCP-11). Both kinds of
+  CLI now build the group from one `mcpGroup(host: McpHost)`.
+- **`appDoctorCommand(app, configuration, { oauthClient? })` — the shared `doctor` for a CLI that is not a
+  messenger**: version, runtime, paths, `store: { path, exists }`, `oauth_client` (`wirecat` or `own`, or the
+  error), `read_only`, `profile_lock`, the config file with its issues — permission keys no command checks
+  included — the profiles and the config file's modes. It opens no keyring, store or network. `appDoctorReport` is
+  the same report for a CLI that renders its own.
+
+### Fixed
+
+- **Each MCP call has its own `run_id`.** A command an agent ran through `<cli>_read` or `<cli>_write`
+  (`runCommandForAgent`) answered with the server process's run id, so two calls of one session had the same
+  `meta.run_id`. Each call now runs in a run of its own, `mcp <command>`, keeping the caller's trace.
+
 ## 0.470.0 — 27.10.2026
 
 ### Changed — may break callers

package/dist/cli/app-doctor-command.d.ts

@@ -0,0 +1,107 @@
+import { Command } from "commander";
+import { type AppIdentity } from "../ports/app.js";
+import type { Configuration } from "./settings.js";
+export interface AppDoctorOptions {
+    /**
+     * Which OAuth client the CLI signs in with — WireCat's or one of the owner's own — read from the environment and
+     * files only. A throw is reported as its message.
+     */
+    oauthClient?: (env: NodeJS.ProcessEnv) => {
+        client: "wirecat" | "own";
+    };
+}
+/**
+ * Run when everything else is broken, so a problem in the config file or the OAuth setting is a field, never a throw.
+ * It reads no keyring, opens no store and calls no service: each can hang or prompt. `fixes` are the `chmod` commands
+ * that make the config private; they go to stderr, not into the answer.
+ */
+export declare const appDoctorReport: (app: AppIdentity, configuration: Configuration, env: NodeJS.ProcessEnv, command: Command, options?: AppDoctorOptions) => {
+    report: {
+        version: string;
+        runtime: {
+            node: string;
+            platform: NodeJS.Platform;
+        };
+        paths: {
+            config: string;
+            state: string;
+            cache: string;
+        };
+        store: {
+            path: string;
+            exists: boolean;
+        };
+        oauth_client?: {
+            client: "wirecat" | "own" | null;
+            error?: string;
+        } | undefined;
+        read_only: string | null;
+        profile_lock: string | null;
+        config: {
+            path: string;
+            found: boolean;
+            issues: import("./config-issues.js").ConfigIssue[];
+        };
+        profiles: string[];
+        files: {
+            checked: false;
+            reason: string;
+        } | {
+            checked: true;
+            ok: boolean;
+            problems: {
+                path: string;
+                mode: string;
+                want: string;
+            }[];
+        };
+    };
+    fixes: string[] | never[];
+} | {
+    report: {
+        version: string;
+        runtime: {
+            node: string;
+            platform: NodeJS.Platform;
+        };
+        paths: {
+            config: string;
+            state: string;
+            cache: string;
+        };
+        store: {
+            path: string;
+            exists: boolean;
+        };
+        oauth_client?: {
+            client: "wirecat" | "own" | null;
+            error?: string;
+        } | undefined;
+        read_only: string | null;
+        profile_lock: string | null;
+        config: {
+            path: string;
+            found: boolean;
+            issues: never[];
+        };
+        settings: {
+            error: string;
+        };
+        profiles: null;
+        files: {
+            checked: false;
+            reason: string;
+        } | {
+            checked: true;
+            ok: boolean;
+            problems: {
+                path: string;
+                mode: string;
+                want: string;
+            }[];
+        };
+    };
+    fixes: string[] | never[];
+};
+/** `doctor` for a CLI that is not a messenger: gcal, drive, zoom. A messenger's is `doctorCommand(messenger)`. */
+export declare const appDoctorCommand: (app: AppIdentity, configuration: Configuration, options?: AppDoctorOptions) => Command;

package/dist/cli/app-doctor-command.js

@@ -0,0 +1,101 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { CliError, configFilePath, resolvePaths } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { Command } from "commander";
+import { envName, readOnlyLockOf } from "../ports/app.js";
+import { storePath } from "../store/path.js";
+import { environmentOf, outputFor } from "./context.js";
+import { LOCAL_READ } from "./effects.js";
+import { itemOf, renderAnswer } from "./envelope.js";
+import { privateFiles } from "./messenger/private-files.js";
+import { unknownPermissionIssues } from "./permission-keys.js";
+import { profileFree } from "./profile.js";
+const failure = (error) => {
+    if (error instanceof CliError)
+        return error.message;
+    throw error;
+};
+const configFiles = (path) => {
+    const files = privateFiles({ files: [path], dirs: [dirname(path)] });
+    if (!files.checked)
+        return { files, fixes: [] };
+    return {
+        files: { ...files, problems: files.problems.map(({ path, mode, want }) => ({ path, mode, want })) },
+        fixes: files.problems.map((problem) => problem.fix),
+    };
+};
+/**
+ * Run when everything else is broken, so a problem in the config file or the OAuth setting is a field, never a throw.
+ * It reads no keyring, opens no store and calls no service: each can hang or prompt. `fixes` are the `chmod` commands
+ * that make the config private; they go to stderr, not into the answer.
+ */
+export const appDoctorReport = (app, configuration, env, command, options = {}) => {
+    const paths = resolvePaths({ appName: app.appName, prefix: app.envPrefix, env });
+    const store = resolve(storePath(env));
+    let oauth;
+    if (options.oauthClient)
+        try {
+            oauth = options.oauthClient(env);
+        }
+        catch (error) {
+            oauth = { client: null, error: failure(error) };
+        }
+    const common = {
+        version: app.version,
+        runtime: { node: process.versions.node, platform: process.platform },
+        paths: { config: paths.config, state: paths.state, cache: paths.cache },
+        store: { path: store, exists: existsSync(store) },
+        ...(oauth ? { oauth_client: oauth } : {}),
+        read_only: readOnlyLockOf(app, env) ?? null,
+        profile_lock: env[envName(app, "PROFILE_LOCK")]?.trim() || null,
+    };
+    try {
+        const settings = configuration.resolveSettings({}, { env, readOnly: true, needsProfile: false, withIssues: true });
+        const { files, fixes } = configFiles(settings.configPath);
+        return {
+            report: {
+                ...common,
+                config: {
+                    path: settings.configPath,
+                    found: settings.configFound,
+                    issues: [
+                        ...(settings.configIssues ?? []),
+                        ...unknownPermissionIssues(command, settings, app.command, configuration.permissions),
+                    ],
+                },
+                profiles: settings.configuredProfiles,
+                files,
+            },
+            fixes,
+        };
+    }
+    catch (error) {
+        const file = configFilePath(paths.config);
+        const { files, fixes } = configFiles(file);
+        return {
+            report: {
+                ...common,
+                config: { path: file, found: existsSync(file), issues: [] },
+                settings: { error: failure(error) },
+                profiles: null,
+                files,
+            },
+            fixes,
+        };
+    }
+};
+/** `doctor` for a CLI that is not a messenger: gcal, drive, zoom. A messenger's is `doctorCommand(messenger)`. */
+export const appDoctorCommand = (app, configuration, options = {}) => profileFree(annotate(new Command("doctor"), {
+    effects: LOCAL_READ,
+    examples: [`${app.command} doctor`, `${app.command} doctor --json`],
+}))
+    .description("check this installation: version, paths, config, profiles, store; no keyring or network")
+    .action(function () {
+    const env = environmentOf(this).env ?? process.env;
+    const { report, fixes } = appDoctorReport(app, configuration, env, this, options);
+    const output = outputFor(this);
+    renderAnswer(this, output, itemOf(report));
+    for (const fix of fixes)
+        output.renderer.note(`to make it private: ${fix}`);
+});

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

@@ -0,0 +1,23 @@
+import type { Command } from "commander";
+import type { AppServerOptions } from "../mcp/app-server.js";
+import type { AppIdentity } from "../ports/app.js";
+import type { Configuration } from "./settings.js";
+export interface AppMcpOptions {
+    /** `Google Calendar`: what the instructions call the service. */
+    name: string;
+    /** The kinds of text other people wrote that the answers carry: `event titles, descriptions, attendee names`. */
+    untrusted: AppServerOptions["untrusted"];
+    /** One of the CLI's permission keys for `--permission`'s help: `calendar.events.delete=deny`. */
+    permissionExample: string;
+    skill?: URL;
+    /** What the CLI alone knows stops a command for a profile, such as an OAuth grant without the scope. */
+    availability?: AppServerOptions["availability"];
+    /** Whether the profile can reach the service, read from disk; left out, `mcp check` does not say. */
+    signedIn?: (profile: string, env: NodeJS.ProcessEnv) => boolean;
+}
+/**
+ * `mcp serve | revoke | server | config | add | check` for a CLI that is not a messenger — the same commands, flags
+ * and answers as a messenger's `mcpCommand`, with `--profiles` and `--permission`, served by the CLI's own program
+ * (`createAppServer`). gcal, drive and zoom mount this instead of an `mcp` of their own.
+ */
+export declare const appMcpCommand: (app: AppIdentity, configuration: Configuration, options: AppMcpOptions) => Command;

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

@@ -0,0 +1,49 @@
+import { baseContext } from "./context.js";
+import { mcpGroup } from "./messenger/mcp-command.js";
+import { refuseUnknownPermissionKeys } from "./permission-keys.js";
+/**
+ * `mcp serve | revoke | server | config | add | check` for a CLI that is not a messenger — the same commands, flags
+ * and answers as a messenger's `mcpCommand`, with `--profiles` and `--permission`, served by the CLI's own program
+ * (`createAppServer`). gcal, drive and zoom mount this instead of an `mcp` of their own.
+ */
+export const appMcpCommand = (app, configuration, options) => {
+    const server = () => ({
+        app,
+        name: options.name,
+        untrusted: options.untrusted,
+        resolveSettings: configuration.resolveSettings,
+        permissions: configuration.permissions,
+        ...(options.skill ? { skill: options.skill } : {}),
+        ...(options.availability ? { availability: options.availability } : {}),
+    });
+    // `mcp serve` has no key of its own, so the shared check before a run never looks at the keys --permission names.
+    const checked = (self, context) => refuseUnknownPermissionKeys(self, context.settings, app.command, configuration.permissions);
+    const host = {
+        app,
+        name: options.name,
+        resolveSettings: configuration.resolveSettings,
+        context: (self, given) => baseContext(self, (flags, resolve) => configuration.resolveSettings(flags, { ...resolve, needsProfile: given?.needsProfile ?? true })),
+        permissionExample: options.permissionExample,
+        serveStdio: async (self, context) => {
+            checked(self, context);
+            const { serveAppOverStdio } = await import("../mcp/app-server.js");
+            await serveAppOverStdio(self, context, server());
+        },
+        serveHttp: async (self, context, http) => {
+            checked(self, context);
+            const { serveAppOverHttp } = await import("../mcp/app-server.js");
+            await serveAppOverHttp(self, context, server(), http);
+        },
+        instructions: async (profiles) => {
+            const { appInstructions } = await import("../mcp/instructions.js");
+            return appInstructions({
+                command: app.command,
+                name: options.name,
+                profile: profiles,
+                untrusted: options.untrusted,
+            });
+        },
+        signedIn: (_self, profile, env) => options.signedIn?.(profile, env),
+    };
+    return mcpGroup(host);
+};

package/dist/cli/index.d.ts

@@ -40,6 +40,8 @@ export { TASK_PAIR_QUERY, TASK_QUERY } from "../services/tasks.js";
 export { answerStdinOption, type Need, type SignInSteps, type SignInStepsOptions, signInSteps, } from "../terminal/sign-in-steps.js";
 export { type AgentPolicy, type AgentTask, type EvaluationResult, evaluateAgent, type Observation, } from "./agent-evaluation.js";
 export { answerEntity } from "./answer-entity.js";
+export { type AppDoctorOptions, appDoctorReport } from "./app-doctor-command.js";
+export type { AppMcpOptions } from "./app-mcp-command.js";
 export type { ApiCommandInput, ApiCommands } from "./bot/api.js";
 export { apiFlagOf, apiJson, apiOptionKey, apiPlainJson, checkApiBody, checkApiParameter, parseApiJson, readApiBody, } from "./bot/api-input.js";
 export { prepareRpcApiBody, type RpcApiBody } from "./bot/api-rpc.js";
@@ -90,7 +92,7 @@ export { terminalAsker } from "./messenger/ask.js";
 export type { CompletionOptions } from "./messenger/complete-command.js";
 export { type ConnectOptions, connectFor, type Messenger, type MessengerContext, messengerContext, type ProfileState, type ReadConnection, type StoredMessages, } from "./messenger/context.js";
 export { COMMAND_NEEDS } from "./messenger/lacks.js";
-export { httpTokenFile, type McpEnvironment, serverEntry } from "./messenger/mcp-command.js";
+export { httpTokenFile, type McpEnvironment, type McpHost, serverEntry } from "./messenger/mcp-command.js";
 export { type MessageItem, messageItem, type ReadMessage } from "./messenger/message-items.js";
 export { type ModeProblem, type PrivateFiles, privateFiles, withSqliteSidecars } from "./messenger/private-files.js";
 export { buildReport as buildDoctorReport, type Report as DoctorReport, type ReportContext as DoctorReportContext, reportFileName as doctorReportFileName, } from "./messenger/report.js";
@@ -111,7 +113,7 @@ export { fieldsOf, projectFields } from "./result-fields.js";
 export { type Config, type Configuration, count, first, flag, fromFile, type GlobalFlags, NONE_NAMED, namedProfile, type ProfileKind, plain, type ResolveOptions, type Settings, type SettingsExtension, type SettingsExtensionContext, type Source, settingsFor, } from "./settings.js";
 export { type PermissionAnswer, readSetupAnswers, type SetupAnswers, setupPermissionCeiling } from "./setup-answers.js";
 export { AGENTS, type Agent, agentFor, screenFor } from "./setup-screen.js";
-export { accountCommand, addMeetingBatchCommand, addMeetingPreparationCommand, addMeetingProjectCandidatesCommand, addMeetingSeriesInventoryCommand, attachmentsCommand, botAdminsCommand, botCommand, botMcpCommand, botMembersCommand, botMessagesCommand, callsCommand, chatsCommand, commandsCommand, completeCommand, configCommand, contactsCommand, conversationsCommand, deleteCommand, doctorCommand, editCommand, floodCommand, forwardCommand, generatedApiCommand, guideCommand, imagesCommand, inboxCommand, markReadCommand, mcpCommand, mentionsCommand, messagesCommand, metadataCommand, modelCatalogueCommand, modelsCommand, pinCommand, pollsCommand, reactionsCommand, recipientsCommand, repliesCommand, reviewCommand, runsCommand, scheduleCommand, searchCommand, searchesCommand, sendCommand, sendsCommand, serveCommand, serverCommand, skillCommand, starCommands, statsCommand, stickersCommand, storeCommand, tagsCommand, tasksCommand, tasksStatsCommand, topicsCommand, unpinCommand, upgradeCommand, watchCommand, } from "./shared-command-exports.js";
+export { accountCommand, addMeetingBatchCommand, addMeetingPreparationCommand, addMeetingProjectCandidatesCommand, addMeetingSeriesInventoryCommand, appDoctorCommand, appMcpCommand, attachmentsCommand, botAdminsCommand, botCommand, botMcpCommand, botMembersCommand, botMessagesCommand, callsCommand, chatsCommand, commandsCommand, completeCommand, configCommand, contactsCommand, conversationsCommand, deleteCommand, doctorCommand, editCommand, floodCommand, forwardCommand, generatedApiCommand, guideCommand, imagesCommand, inboxCommand, markReadCommand, mcpCommand, mentionsCommand, messagesCommand, metadataCommand, modelCatalogueCommand, modelsCommand, pinCommand, pollsCommand, reactionsCommand, recipientsCommand, repliesCommand, reviewCommand, runsCommand, scheduleCommand, searchCommand, searchesCommand, sendCommand, sendsCommand, serveCommand, serverCommand, skillCommand, starCommands, statsCommand, stickersCommand, storeCommand, tagsCommand, tasksCommand, tasksStatsCommand, topicsCommand, unpinCommand, upgradeCommand, watchCommand, } from "./shared-command-exports.js";
 export { assertSharedContracts, customizeSharedCommand, hasSharedContract, overrideSharedContract, type SharedContractOverride, sharedContractOverrides, sharedContracts, } from "./shared-contracts.js";
 export { runnable, withSafety } from "./steps.js";
 export { type StoreInfo, sharedStoreCommand, storeInfo, storeInfoCommand } from "./store-info.js";

package/dist/cli/index.js

@@ -35,6 +35,7 @@ export { TASK_PAIR_QUERY, TASK_QUERY } from "../services/tasks.js";
 export { answerStdinOption, signInSteps, } from "../terminal/sign-in-steps.js";
 export { evaluateAgent, } from "./agent-evaluation.js";
 export { answerEntity } from "./answer-entity.js";
+export { appDoctorReport } from "./app-doctor-command.js";
 export { apiFlagOf, apiJson, apiOptionKey, apiPlainJson, checkApiBody, checkApiParameter, parseApiJson, readApiBody, } from "./bot/api-input.js";
 export { prepareRpcApiBody } from "./bot/api-rpc.js";
 export { botContext, botWords } from "./bot/context.js";
@@ -102,7 +103,7 @@ export { fieldsOf, projectFields } from "./result-fields.js";
 export { count, first, flag, fromFile, NONE_NAMED, namedProfile, plain, settingsFor, } from "./settings.js";
 export { readSetupAnswers, setupPermissionCeiling } from "./setup-answers.js";
 export { AGENTS, agentFor, screenFor } from "./setup-screen.js";
-export { accountCommand, addMeetingBatchCommand, addMeetingPreparationCommand, addMeetingProjectCandidatesCommand, addMeetingSeriesInventoryCommand, attachmentsCommand, botAdminsCommand, botCommand, botMcpCommand, botMembersCommand, botMessagesCommand, callsCommand, chatsCommand, commandsCommand, completeCommand, configCommand, contactsCommand, conversationsCommand, deleteCommand, doctorCommand, editCommand, floodCommand, forwardCommand, generatedApiCommand, guideCommand, imagesCommand, inboxCommand, markReadCommand, mcpCommand, mentionsCommand, messagesCommand, metadataCommand, modelCatalogueCommand, modelsCommand, pinCommand, pollsCommand, reactionsCommand, recipientsCommand, repliesCommand, reviewCommand, runsCommand, scheduleCommand, searchCommand, searchesCommand, sendCommand, sendsCommand, serveCommand, serverCommand, skillCommand, starCommands, statsCommand, stickersCommand, storeCommand, tagsCommand, tasksCommand, tasksStatsCommand, topicsCommand, unpinCommand, upgradeCommand, watchCommand, } from "./shared-command-exports.js";
+export { accountCommand, addMeetingBatchCommand, addMeetingPreparationCommand, addMeetingProjectCandidatesCommand, addMeetingSeriesInventoryCommand, appDoctorCommand, appMcpCommand, attachmentsCommand, botAdminsCommand, botCommand, botMcpCommand, botMembersCommand, botMessagesCommand, callsCommand, chatsCommand, commandsCommand, completeCommand, configCommand, contactsCommand, conversationsCommand, deleteCommand, doctorCommand, editCommand, floodCommand, forwardCommand, generatedApiCommand, guideCommand, imagesCommand, inboxCommand, markReadCommand, mcpCommand, mentionsCommand, messagesCommand, metadataCommand, modelCatalogueCommand, modelsCommand, pinCommand, pollsCommand, reactionsCommand, recipientsCommand, repliesCommand, reviewCommand, runsCommand, scheduleCommand, searchCommand, searchesCommand, sendCommand, sendsCommand, serveCommand, serverCommand, skillCommand, starCommands, statsCommand, stickersCommand, storeCommand, tagsCommand, tasksCommand, tasksStatsCommand, topicsCommand, unpinCommand, upgradeCommand, watchCommand, } from "./shared-command-exports.js";
 export { assertSharedContracts, customizeSharedCommand, hasSharedContract, overrideSharedContract, sharedContractOverrides, sharedContracts, } from "./shared-contracts.js";
 export { runnable, withSafety } from "./steps.js";
 export { sharedStoreCommand, storeInfo, storeInfoCommand } from "./store-info.js";

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

@@ -1,9 +1,10 @@
 import { type ChildProcessWithoutNullStreams } from "node:child_process";
 import { Command } from "commander";
 import type { ServerSystem } from "../../background/system.js";
+import type { HttpOptions } from "../../mcp/http/serve.js";
 import { type AppIdentity } from "../../ports/app.js";
-import { type BaseEnvironment } from "../context.js";
-import { type Settings } from "../settings.js";
+import { type BaseContext, type BaseEnvironment } from "../context.js";
+import { type GlobalFlags, type ResolveOptions, type Settings } from "../settings.js";
 import { type Messenger } from "./context.js";
 /** Where the running CLI really lives; a test hands in its own. */
 export interface McpEnvironment extends BaseEnvironment {
@@ -38,7 +39,7 @@ export interface ProfileSet {
  * takes the place of `<PREFIX>_PROFILE`; under `<PREFIX>_PROFILE_LOCK` it may name the locked profile only
  * (WC-ACCT-5).
  */
-export declare const servedProfiles: (self: Command, messenger: Messenger, { settings, env }: {
+export declare const servedProfiles: (self: Command, messenger: Pick<Messenger, "app" | "resolveSettings">, { settings, env }: {
     settings: Pick<Settings, "profile" | "sources" | "profilesHere">;
     env: NodeJS.ProcessEnv;
 }, given: string | undefined, words: string) => {
@@ -48,7 +49,32 @@ export declare const servedProfiles: (self: Command, messenger: Messenger, { set
 };
 /** Where `mcp serve --http` keeps the hashes of the tokens it issued — per profile, in the state folder. */
 export declare const httpTokenFile: (app: AppIdentity, profile: string, env: NodeJS.ProcessEnv) => string;
+/**
+ * What the `mcp` group needs of the CLI it serves. A messenger serves through its one connection (`messengerHost`);
+ * a CLI that is not a messenger through its own program (`appMcpCommand`). The commands, flags and answers are the
+ * same in both, so every WireCat CLI has one `mcp`.
+ */
+export interface McpHost {
+    app: AppIdentity;
+    /** `Telegram`, `Google Calendar`: what the instructions call the service. */
+    name: string;
+    resolveSettings: (flags: GlobalFlags, options?: ResolveOptions) => Settings;
+    context: (self: Command, options?: {
+        needsProfile?: boolean;
+    }) => BaseContext;
+    /** A permission key of this CLI for `--permission`'s help: `messages.send=deny`. */
+    permissionExample: string;
+    serveStdio: (self: Command, context: BaseContext) => Promise<void>;
+    serveHttp: (self: Command, context: BaseContext, http: Omit<HttpOptions, "onCode" | "onError" | "appName">) => Promise<void>;
+    /** The instructions of the server of several profiles, whose tools each take `profile`. */
+    instructions: (profiles: readonly string[]) => string | Promise<string>;
+    /** Whether the profile can reach the service; `undefined` where the CLI cannot tell without connecting. */
+    signedIn: (self: Command, profile: string, env: NodeJS.ProcessEnv) => boolean | undefined;
+    /** A profile that is a bot, or not signed in here; the server of several profiles leaves bots out. */
+    profileState?: Messenger["profileState"];
+}
 export declare const mcpCommand: (messenger: Messenger) => Command;
+export declare const mcpGroup: (host: McpHost) => Command;
 /** How the startup and status lines name a set, so the owner sees which accounts an agent reaches. */
 export declare const profileSetLabel: (set: ProfileSet) => string;
 /**

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

@@ -66,13 +66,42 @@ export const servedProfiles = (self, messenger, { settings, env }, given, words)
 const withProfiles = (command) => command.option("--profiles <names|all>", "serve several profiles from one server instead of one: names, comma-separated, or all for every profile");
 /** Where `mcp serve --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]);
-export const mcpCommand = (messenger) => {
-    const { app } = messenger;
+const withFlags = (command, example) => command.option("--permission <key=level>", `make a permission stricter for this server only, like ${example}; it never loosens the profile; repeat for more keys`, (value, previous = []) => [...previous, value]);
+const messengerHost = (messenger) => ({
+    app: messenger.app,
+    name: messenger.name ?? messenger.app.command,
+    resolveSettings: messenger.resolveSettings,
+    ...(messenger.profileState ? { profileState: messenger.profileState } : {}),
+    context: (self, options) => messengerContext(self, messenger, options),
+    permissionExample: "messages.send=deny",
+    serveStdio: async (self, context) => {
+        // Loaded here, not at the top: every other command would otherwise pay for the SDK.
+        const { serveOverStdio } = await import("../../mcp/server.js");
+        await serveOverStdio(self, context, messenger, {});
+    },
+    serveHttp: async (self, context, http) => {
+        const { serveOverHttpUntilStopped } = await import("../../mcp/server.js");
+        await serveOverHttpUntilStopped(self, context, messenger, {}, http);
+    },
+    instructions: async (profiles) => {
+        const { instructions } = await import("../../mcp/instructions.js");
+        return instructions({
+            command: messenger.app.command,
+            name: messenger.name ?? messenger.app.command,
+            profile: profiles,
+            writes: [],
+        });
+    },
+    signedIn: (self, profile, env) => (messenger.accountOf?.(self) ?? recalledAccount(messenger.app, messenger.provider, profile, env)) !== undefined,
+});
+export const mcpCommand = (messenger) => mcpGroup(messengerHost(messenger));
+export const mcpGroup = (host) => {
+    const { app } = host;
+    const flagged = (command) => withFlags(command, host.permissionExample);
     const command = annotate(new Command("mcp"), { effects: LOCAL_READ, mcp: false })
         .summary("serve this profile's commands to an AI agent, and set that up")
         .description(`serve this profile to an agent over MCP and set it up — \`claude mcp add ${app.command} -- ${app.command} <profile> mcp serve\``);
-    command.addCommand(withProfiles(withFlags(annotate(new Command("serve"), {
+    command.addCommand(withProfiles(flagged(annotate(new Command("serve"), {
         effects: REMOTE_WRITE,
         lifetime: "persistent",
         mcp: false,
@@ -89,10 +118,10 @@ export const mcpCommand = (messenger) => {
         .option("--public-url <url>", "the tunnel's https address the browser apps use, e.g. https://<name>.ts.net or https://<name>.ts.net/tg")
         .action(async function () {
         const flags = this.optsWithGlobals();
-        const context = messengerContext(this, messenger, { needsProfile: false });
-        const served = servedProfiles(this, messenger, context, flags.profiles, "mcp serve");
+        const context = host.context(this, { needsProfile: false });
+        const served = servedProfiles(this, host, context, flags.profiles, "mcp serve");
         if ("set" in served)
-            return serveProfiles(this, context, messenger, flags, served.set);
+            return serveProfiles(this, context, host, flags, served.set);
         const { profile } = served;
         if (flags.http) {
             const publicUrl = publicUrlOf(flags.publicUrl, {
@@ -100,9 +129,8 @@ export const mcpCommand = (messenger) => {
                 reaches: `the browser apps reach ${app.command}`,
                 path: true,
             });
-            const { serveOverHttpUntilStopped } = await import("../../mcp/server.js");
             const tokenFile = httpTokenFile(app, profile, context.env);
-            await serveOverHttpUntilStopped(this, context, messenger, {}, {
+            await host.serveHttp(this, context, {
                 publicUrl,
                 port: portOf(flags.port, DEFAULT_PORT),
                 tokenFile,
@@ -111,9 +139,7 @@ export const mcpCommand = (messenger) => {
             });
             return;
         }
-        // Loaded here, not at the top: every other command would otherwise pay for the SDK.
-        const { serveOverStdio } = await import("../../mcp/server.js");
-        await serveOverStdio(this, context, messenger, {});
+        await host.serveStdio(this, context);
     }));
     command.addCommand(withProfiles(annotate(new Command("revoke"), {
         effects: LOCAL_WRITE,
@@ -122,8 +148,8 @@ export const mcpCommand = (messenger) => {
     })
         .summary("forget every login given to a browser app")
         .description("forget every login `mcp serve --http` gave a browser app, of this profile or of the server `--profiles` names; each app must log in again")).action(async function () {
-        const context = messengerContext(this, messenger, { needsProfile: false });
-        const served = servedProfiles(this, messenger, context, this.opts().profiles, "mcp revoke");
+        const context = host.context(this, { needsProfile: false });
+        const served = servedProfiles(this, host, context, this.opts().profiles, "mcp revoke");
         const { revokeAll } = await import("../../mcp/http/oauth.js");
         revokeAll(httpTokenFile(app, "set" in served ? served.set.key : served.profile, context.env));
         renderAnswer(this, context, itemOf("set" in served
@@ -135,9 +161,9 @@ export const mcpCommand = (messenger) => {
         permission: true,
         profiles: true,
         target: (self) => {
-            const context = messengerContext(self, messenger, { needsProfile: false });
+            const context = host.context(self, { needsProfile: false });
             const { env } = context;
-            const served = servedProfiles(self, messenger, context, self.opts().profiles, `mcp server ${self.name()}`);
+            const served = servedProfiles(self, host, context, self.opts().profiles, `mcp server ${self.name()}`);
             if ("set" in served) {
                 const { set } = served;
                 return {
@@ -162,20 +188,20 @@ export const mcpCommand = (messenger) => {
                 version: app.version,
             };
         },
-        answer: (self, item, lines) => renderAnswer(self, messengerContext(self, messenger, { needsProfile: false }), itemOf(item), () => lines.join("\n")),
+        answer: (self, item, lines) => renderAnswer(self, host.context(self, { needsProfile: false }), itemOf(item), () => lines.join("\n")),
         system: (self) => environmentOf(self).system,
     }));
-    command.addCommand(withProfiles(withFlags(annotate(new Command("config"), {
+    command.addCommand(withProfiles(flagged(annotate(new Command("config"), {
         effects: LOCAL_READ,
         examples: [`${app.command} personal mcp config`, `${app.command} mcp config --profiles all`],
     })
         .summary("print the local MCP configuration of this profile, or of those --profiles names")
         .description("print the mcpServers entry for Claude Desktop, Cursor and others, with full paths; writes nothing"))).action(async function () {
         const flags = this.optsWithGlobals();
-        const context = messengerContext(this, messenger, { needsProfile: false });
+        const context = host.context(this, { needsProfile: false });
         const { env } = context;
         const given = environmentOf(this).mcp ?? {};
-        const served = servedProfiles(this, messenger, context, flags.profiles, "mcp config");
+        const served = servedProfiles(this, host, context, flags.profiles, "mcp config");
         const entry = serverEntry(app, {
             ...("set" in served ? { profiles: served.set.option } : { profile: served.profile }),
             flags,
@@ -190,7 +216,7 @@ export const mcpCommand = (messenger) => {
                 : [],
         }), () => JSON.stringify(entry.config, null, 2));
     }));
-    command.addCommand(withFlags(grantsAuthority(annotate(new Command("add"), {
+    command.addCommand(flagged(grantsAuthority(annotate(new Command("add"), {
         effects: LOCAL_WRITE,
         examples: [`${app.command} personal mcp add codex --allow-writes`],
     }))
@@ -199,7 +225,7 @@ export const mcpCommand = (messenger) => {
         .option("--allow-writes", "acknowledge that this profile offers writing tools")).action(async function (client) {
         if (client !== "codex" && client !== "claude-code")
             throw new CliError("validation_error", "choose codex or claude-code");
-        const context = messengerContext(this, messenger);
+        const context = host.context(this);
         const { settings, env } = context;
         const given = environmentOf(this).mcp ?? {};
         const configuration = serverEntry(app, {
@@ -224,11 +250,11 @@ export const mcpCommand = (messenger) => {
             throw new CliError("validation_error", error instanceof Error ? error.message : "MCP setup failed");
         }
     }));
-    command.addCommand(withFlags(annotate(new Command("check"), {
+    command.addCommand(flagged(annotate(new Command("check"), {
         effects: LOCAL_READ,
         examples: [`${app.command} personal mcp check`],
     }).description("check this profile's local MCP handshake and tool list")).action(async function () {
-        const context = messengerContext(this, messenger);
+        const context = host.context(this);
         const { settings, env } = context;
         const given = environmentOf(this).mcp ?? {};
         const configuration = serverEntry(app, {
@@ -247,8 +273,8 @@ export const mcpCommand = (messenger) => {
             const { tools, potentialWrites } = await probeStdio(entry, {
                 start: stderr.start,
             });
-            const account = messenger.accountOf?.(this) ?? recalledAccount(app, messenger.provider, settings.profile, env);
-            if (!account) {
+            const signedIn = host.signedIn(this, settings.profile, env);
+            if (signedIn === false) {
                 const setup = rootOf(this).commands.some((one) => one.name() === "setup")
                     ? ` — log in with \`${app.command} ${settings.profile} setup\``
                     : "";
@@ -256,9 +282,9 @@ export const mcpCommand = (messenger) => {
                     `tools will fail${setup}`);
             }
             renderAnswer(this, context, itemOf({
-                healthy: account !== undefined,
+                healthy: signedIn !== false,
                 profile: settings.profile,
-                signed_in: account !== undefined,
+                signed_in: signedIn ?? null,
                 tools: tools.length,
                 potential_writes: potentialWrites.length,
             }));
@@ -282,11 +308,11 @@ export const profileSetLabel = (set) => {
  * `<tool> <profile> mcp serve` (`src/mcp/all-profiles.ts`). Nothing picks a profile: each tool takes one, and the
  * agent is told to ask.
  */
-const serveProfiles = async (self, context, messenger, flags, set) => {
-    const { app } = messenger;
+const serveProfiles = async (self, context, host, flags, set) => {
+    const { app } = host;
     const { env } = context;
     const tokenFile = httpTokenFile(app, set.key, env);
-    const state = (profile) => messenger.profileState?.(profile, env) ?? "signed-in";
+    const state = (profile) => host.profileState?.(profile, env) ?? "signed-in";
     const bots = set.option === EVERY_PROFILE ? [] : set.profiles().filter((profile) => state(profile) === "bot");
     if (bots.length > 0)
         throw new CliError("validation_error", `${bots.join(", ")} ${bots.length === 1 ? "is a bot profile" : "are bot profiles"}, served by \`${app.command} <profile> bot mcp serve\``);
@@ -298,22 +324,16 @@ const serveProfiles = async (self, context, messenger, flags, set) => {
     const execPath = given.execPath ?? process.execPath;
     const scriptPath = given.scriptPath ?? realpathSync(process.argv[1] ?? "");
     const tightened = (flags.permission ?? []).flatMap((entry) => ["--permission", entry]);
-    const { instructions } = await import("../../mcp/instructions.js");
     const options = {
         command: app.command,
         version: app.version,
-        name: messenger.name ?? app.command,
+        name: host.name,
         profiles,
         signedIn: (profile) => state(profile) === "signed-in",
         signIn: (profile) => `profile ${profile} is not signed in — run \`${app.command} ${profile} setup\`, or sign in from WireCat Desktop, ` +
             "then try again. If the owner did not choose this profile, ask which one.",
         child: (profile) => ({ command: execPath, args: [scriptPath, profile, "mcp", "serve", ...tightened], env }),
-        instructions: instructions({
-            command: app.command,
-            name: messenger.name ?? app.command,
-            profile: profiles(),
-            writes: [],
-        }),
+        instructions: await host.instructions(profiles()),
         note: (line) => context.renderer.note(line),
     };
     if (flags.http) {