@happyvertical/smrt-app-cli 0.30.0

package/AGENTS.md

@@ -0,0 +1,22 @@
+# @happyvertical/smrt-app-cli
+
+Application CLI support for SMRT-based apps.
+
+## Purpose
+
+- Provides reusable app-facing CLI commands, currently centered on authenticated device-code login flows.
+- Stores app CLI configuration in a namespaced local config file selected by the consuming app context.
+- Intended for downstream apps that need a branded CLI without reimplementing auth polling, config persistence, and server URL handling.
+
+## Patterns
+
+- Keep commands app-agnostic; pass app identity through `CliConfigContext`.
+- Treat transient auth polling failures as recoverable until the server-issued expiration window closes.
+- Do not persist tokens, server URLs, or app slugs outside the configured local CLI config path.
+- Keep command output stream-injectable so tests can assert behavior without writing to the real terminal.
+
+## Gotchas
+
+- This package depends on `@happyvertical/smrt-users` for the server-side auth contract but should not import app-specific user models.
+- Device-code login polling should distinguish pending approval, transient server/network failures, expiry, and hard auth rejection.
+- Tests should isolate config paths with package-specific environment prefixes.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

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

package/dist/bin/smrt-mcp-bridge.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `smrt-mcp-bridge` — generic stdio MCP bridge.
+ *
+ * Usage:
+ *
+ * ```
+ * smrt-mcp-bridge --env-prefix=WILLGRIFFIN \
+ *   --name=willgriffin-mcp --version=0.1.0
+ * ```
+ *
+ * All options can also be passed as env vars:
+ *
+ *  - `SMRT_MCP_ENV_PREFIX` — env-prefix the bridge uses to look up the app's
+ *    server URL/token/config file.
+ *  - `SMRT_MCP_APP_SLUG` — directory name under `~/.config`.
+ *  - `SMRT_MCP_SERVER_NAME` / `SMRT_MCP_SERVER_VERSION` — local server identity.
+ *  - `SMRT_MCP_DEFAULT_SERVER_URL` — fallback server URL.
+ *
+ * Apps that want their own branded bin should call `runMcpStdioBridge`
+ * directly from `@happyvertical/smrt-app-mcp/cli` instead of going through
+ * this generic entrypoint.
+ */
+export {};
+//# sourceMappingURL=smrt-mcp-bridge.d.ts.map

package/dist/bin/smrt-mcp-bridge.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { d as runMcpStdioBridge } from "../config-Bgq_EQoJ.js";
+function readArg(name) {
+  const prefix = `--${name}=`;
+  const match = process.argv.find((arg) => arg.startsWith(prefix));
+  if (match) return match.slice(prefix.length);
+  const flagIdx = process.argv.indexOf(`--${name}`);
+  if (flagIdx >= 0 && flagIdx + 1 < process.argv.length) {
+    return process.argv[flagIdx + 1];
+  }
+  return void 0;
+}
+const envPrefix = readArg("env-prefix") ?? process.env.SMRT_MCP_ENV_PREFIX ?? "";
+if (!envPrefix) {
+  console.error(
+    "smrt-mcp-bridge: --env-prefix=<PREFIX> (or SMRT_MCP_ENV_PREFIX) is required."
+  );
+  process.exit(2);
+}
+const appSlug = readArg("app-slug") ?? process.env.SMRT_MCP_APP_SLUG;
+const defaultServerUrl = readArg("default-server-url") ?? process.env.SMRT_MCP_DEFAULT_SERVER_URL;
+const serverName = readArg("name") ?? process.env.SMRT_MCP_SERVER_NAME ?? "smrt-app-mcp";
+const serverVersion = readArg("version") ?? process.env.SMRT_MCP_SERVER_VERSION ?? "0.0.0";
+await runMcpStdioBridge({
+  envPrefix,
+  appSlug,
+  defaultServerUrl,
+  serverInfo: { name: serverName, version: serverVersion }
+});

package/dist/config-Bgq_EQoJ.js

@@ -0,0 +1,206 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { randomBytes } from "node:crypto";
+import { readFile, mkdir, chmod, writeFile, rename, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+function createMcpStdioBridge(options) {
+  const toolsPath = options.toolsPath ?? "/api/mcp/tools";
+  const callPath = options.callPath ?? "/api/mcp/call";
+  const server = new Server(options.serverInfo, {
+    capabilities: { tools: {} }
+  });
+  server.setRequestHandler(
+    ListToolsRequestSchema,
+    async (_request) => {
+      return requestJson(
+        options,
+        toolsPath,
+        { method: "GET" },
+        { fetch: options.fetch }
+      );
+    }
+  );
+  server.setRequestHandler(
+    CallToolRequestSchema,
+    async (request) => {
+      const { name, arguments: args = {} } = request.params;
+      try {
+        return await requestJson(
+          options,
+          callPath,
+          {
+            body: JSON.stringify({ arguments: args, name }),
+            method: "POST"
+          },
+          { fetch: options.fetch }
+        );
+      } catch (error) {
+        return {
+          content: [
+            {
+              text: error instanceof Error ? error.message : "MCP tool call failed.",
+              type: "text"
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  return {
+    server,
+    connect: () => server.connect(new StdioServerTransport())
+  };
+}
+async function runMcpStdioBridge(options) {
+  const { connect } = createMcpStdioBridge(options);
+  await connect();
+}
+const bridge = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  createMcpStdioBridge,
+  runMcpStdioBridge
+}, Symbol.toStringTag, { value: "Module" }));
+const DEFAULT_LOCAL_SERVER = "http://localhost:5173";
+function configFilePath(context) {
+  const override = process.env[`${context.envPrefix}_CLI_CONFIG`];
+  if (override) return override;
+  const slug = context.appSlug ?? context.envPrefix.toLowerCase();
+  return join(homedir(), ".config", slug, "config.json");
+}
+async function loadCliConfig(context) {
+  try {
+    const raw = await readFile(configFilePath(context), "utf8");
+    if (!raw.trim()) return {};
+    return JSON.parse(raw);
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return {};
+    }
+    throw error;
+  }
+}
+async function saveCliConfig(context, config) {
+  const path = configFilePath(context);
+  const dir = dirname(path);
+  await mkdir(dir, { recursive: true, mode: 448 });
+  await chmod(dir, 448).catch(() => void 0);
+  const tmp = `${path}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    await writeFile(tmp, `${JSON.stringify(config, null, 2)}
+`, {
+      mode: 384
+    });
+    await chmod(tmp, 384);
+    await rename(tmp, path);
+  } catch (err) {
+    await unlink(tmp).catch(() => void 0);
+    throw err;
+  }
+}
+async function getServerUrl(context, config) {
+  const resolved = config ?? await loadCliConfig(context);
+  const url = process.env[`${context.envPrefix}_SERVER_URL`] ?? resolved.serverUrl ?? context.defaultServerUrl ?? DEFAULT_LOCAL_SERVER;
+  return url.replace(/\/+$/u, "");
+}
+async function getStoredToken(context, config) {
+  const resolved = config ?? await loadCliConfig(context);
+  return process.env[`${context.envPrefix}_TOKEN`] ?? resolved.token;
+}
+async function clearStoredToken(context) {
+  const config = await loadCliConfig(context);
+  delete config.token;
+  await saveCliConfig(context, config);
+}
+async function saveAuth(context, serverUrl, token) {
+  const config = await loadCliConfig(context);
+  await saveCliConfig(context, {
+    ...config,
+    serverUrl: serverUrl.replace(/\/+$/u, ""),
+    token
+  });
+}
+const DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+async function requestJson(context, path, init = {}, options = {}) {
+  const config = options.loadedConfig ?? await loadCliConfig(context);
+  const serverUrl = (options.serverUrl ?? await getServerUrl(context, config)).replace(/\/+$/u, "");
+  const token = await getStoredToken(context, config);
+  const headers = new Headers(init.headers);
+  if (options.requireAuth && options.auth !== false && !token) {
+    throw new Error(
+      `Not authenticated. Run \`${context.envPrefix.toLowerCase()} auth login\` first.`
+    );
+  }
+  if (!headers.has("content-type") && init.body) {
+    headers.set("content-type", "application/json");
+  }
+  if (options.auth !== false && token) {
+    headers.set("authorization", `Bearer ${token}`);
+  }
+  const fetchImpl = options.fetch ?? fetch;
+  const response = await fetchImpl(`${serverUrl}${path}`, {
+    ...init,
+    headers
+  });
+  const contentType = response.headers.get("content-type") ?? "";
+  const maxBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+  const text = await readBodyWithCap(response, maxBytes);
+  const parsed = contentType.includes("application/json") && text ? JSON.parse(text) : text;
+  if (!response.ok) {
+    const message = parsed && typeof parsed === "object" && "error" in parsed ? String(parsed.error) : `HTTP ${response.status}: ${response.statusText}`;
+    throw Object.assign(new Error(message), { status: response.status });
+  }
+  return parsed;
+}
+async function readBodyWithCap(response, maxBytes) {
+  if (!response.body) return "";
+  const cl = Number(response.headers.get("content-length") ?? "");
+  if (Number.isFinite(cl) && cl > maxBytes) {
+    try {
+      await response.body.cancel();
+    } catch {
+    }
+    throw new Error(
+      `Response too large: ${cl} bytes exceeds ${maxBytes}-byte cap`
+    );
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      size += value.byteLength;
+      if (size > maxBytes) {
+        throw new Error(
+          `Response too large: exceeded ${maxBytes}-byte cap mid-stream`
+        );
+      }
+      chunks.push(value);
+    }
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+    }
+  }
+  return new TextDecoder().decode(
+    Buffer.concat(chunks.map((c) => Buffer.from(c)))
+  );
+}
+export {
+  getStoredToken as a,
+  createMcpStdioBridge as b,
+  clearStoredToken as c,
+  runMcpStdioBridge as d,
+  saveCliConfig as e,
+  bridge as f,
+  getServerUrl as g,
+  loadCliConfig as l,
+  requestJson as r,
+  saveAuth as s
+};

package/dist/index.d.ts

@@ -0,0 +1,369 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Writable } from 'node:stream';
+
+declare type ApiHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+export declare interface AppCli {
+    run(argv: string[]): Promise<void>;
+    /**
+     * Wire up the stdio MCP bridge and connect to stdin/stdout. The CLI
+     * advertises itself to local MCP clients as `serverInfo.name` /
+     * `.version`. Both fields default from `options.name` (so a brand-
+     * new app gets `{ name: '<name>-mcp', version: '0.0.0' }`) — pass an
+     * explicit object to override.
+     */
+    startMcpBridge(serverInfo?: {
+        name?: string;
+        version?: string;
+    }): Promise<void>;
+}
+
+export declare interface AppCliCommand {
+    name: string;
+    description: string;
+    /**
+     * When true, the CLI ensures resources are fetched and available via
+     * `ctx.getResources()` before `run()` is called. Default `false`.
+     */
+    needsResources?: boolean;
+    run(args: string[], ctx: AppCliContext): Promise<void>;
+}
+
+export declare interface AppCliContext {
+    config: CliConfig;
+    serverUrl: string;
+    token?: string;
+    /** Lazy resource-list fetch. Cached for the duration of the CLI invocation. */
+    getResources(): Promise<ResourceListResponse>;
+    /** Issue a JSON request via the shared client. */
+    requestJson<T = unknown>(path: string, init?: RequestInit, options?: RequestJsonOptions): Promise<T>;
+    /** Issue a raw fetch (for streaming / content-type-aware responses). */
+    request(path: string, init?: RequestInit): Promise<Response>;
+    stdout: NodeJS.WriteStream;
+    stderr: NodeJS.WriteStream;
+}
+
+export declare function buildFlagParser(schema: Record<string, unknown> | undefined, options?: ParserOptions): BuildParserResult;
+
+export declare interface BuildParserResult {
+    /** Parses argv tail (everything after `<cli> <slug> <cmd> [id]`). */
+    parse(argv: string[], httpMethod: string): ParsedArgs;
+    /** Status of the underlying schema. */
+    status: SchemaSupportStatus;
+}
+
+/**
+ * Build only the URL — exposed for tests.
+ */
+export declare function buildUrl(context: CliConfigContext, resource: CliResource, command: CommandDefinition, parsed: ParsedArgs, id?: string): Promise<string>;
+
+/**
+ * Classify a JSONSchema. The CLI uses this to decide between rich flag
+ * parsing and the positional JSON escape hatch.
+ */
+export declare function classifySchema(schema: Record<string, unknown> | undefined): SchemaSupportStatus;
+
+/** Remove the token from the config file (e.g. on logout). */
+export declare function clearStoredToken(context: CliConfigContext): Promise<void>;
+
+/** Shape stored on disk in the app's CLI config file. */
+export declare interface CliConfig {
+    serverUrl?: string;
+    token?: string;
+}
+
+/**
+ * Configuration for the env-var/config-file resolution chain.
+ *
+ * Env vars derived from `envPrefix`:
+ *
+ *  - `${PREFIX}_SERVER_URL`
+ *  - `${PREFIX}_TOKEN`
+ *  - `${PREFIX}_CLI_CONFIG` (overrides config file path)
+ */
+export declare interface CliConfigContext {
+    /**
+     * Uppercase prefix for env vars and the app's namespaced config dir.
+     * Example: `WILLGRIFFIN` → reads `WILLGRIFFIN_SERVER_URL`, defaults the
+     * config file to `~/.config/willgriffin/config.json` unless `appSlug`
+     * overrides the directory name.
+     */
+    envPrefix: string;
+    /** Directory name under `~/.config`. Defaults to lowercased `envPrefix`. */
+    appSlug?: string;
+    /** Fallback server URL if neither env nor config sets one. */
+    defaultServerUrl?: string;
+}
+
+export declare type CliResource = CliResource_2;
+
+declare interface CliResource_2 {
+    /** Kebab-case identifier; the first positional argument after the CLI name. */
+    slug: string;
+    className: string;
+    qualifiedName?: string;
+    packageName?: string;
+    label: string;
+    /** Collection segment, no leading slash, no `/api` prefix. */
+    apiPath: string;
+    commands: CommandDefinition_2[];
+}
+
+export declare type CommandDefinition = CommandDefinition_2;
+
+declare interface CommandDefinition_2 {
+    /** Method name in source casing — source of truth for HTTP routing. */
+    methodName: string;
+    /** Kebab-case identifier used by the CLI argv parser. */
+    commandName: string;
+    kind: CommandKind_2;
+    scope: CommandScope_2;
+    httpMethod: ApiHttpMethod;
+    /** URL path segments after `/<apiPath>[/<id>]/`. May be empty. */
+    pathSegments: string[];
+    description?: string;
+    /** JSONSchema describing the command's argv-flag surface. */
+    parameters?: Record<string, unknown>;
+}
+
+export declare type CommandKind = CommandKind_2;
+
+declare type CommandKind_2 = 'crud' | 'custom';
+
+export declare type CommandScope = CommandScope_2;
+
+declare type CommandScope_2 = 'item' | 'collection';
+
+export declare function createAppCli(options: CreateAppCliOptions): AppCli;
+
+export declare interface CreateAppCliOptions {
+    /** Display + branding name, e.g. `willgriffin`. Also drives `envPrefix`. */
+    name: string;
+    /** Override the env-var prefix. Default: `name.toUpperCase()`. */
+    envPrefix?: string;
+    /** Override the config dir slug. Default: `name.toLowerCase()`. */
+    configDir?: string;
+    /** Baked-in default server URL when neither env nor config sets one. */
+    defaultServerUrl?: string;
+    /**
+     * App-specific commands. Dispatched BEFORE built-ins (`auth`,
+     * `resources`, `mcp`) and before the resource-slug dispatcher, so an
+     * `extraCommands` entry takes precedence over anything with the same
+     * top-level argv.
+     *
+     * - **Built-in shadowing** (`extraCommands: [{ name: 'mcp' }]`): the CLI
+     *   prints a one-line stderr warning on first invocation. The extra
+     *   command still wins, but the warning makes the override visible.
+     *
+     * - **Resource-slug shadowing** (`extraCommands: [{ name: 'praecos' }]`
+     *   when a server-side class also resolves to slug `praecos`): the
+     *   extra command silently wins. There's no warning because checking
+     *   would require a discovery round-trip on every invocation. Authors
+     *   are responsible for namespacing their extra commands (e.g. prefix
+     *   with the app name) to avoid accidental shadowing as the server's
+     *   class registry grows. (#1311 review C-2.)
+     */
+    extraCommands?: AppCliCommand[];
+}
+
+/**
+ * Wire up the stdio server. Use `runMcpStdioBridge` for a one-call entry
+ * point in `bin/` scripts; this lower-level form is exposed for tests.
+ */
+export declare function createMcpStdioBridge(options: McpStdioBridgeOptions): {
+    server: Server;
+    connect: () => Promise<void>;
+};
+
+/**
+ * Fetch the discovery payload.
+ *
+ * Translates a 401 into a friendlier error so the CLI can prompt the
+ * user to log in rather than dumping a raw HTTP error.
+ */
+export declare function fetchResourceList(context: CliConfigContext, options?: FetchResourceListOptions): Promise<ResourceListResponse>;
+
+declare interface FetchResourceListOptions {
+    /** Endpoint path on the server. Default `/api/_resources`. */
+    path?: string;
+    /** Custom fetch (tests). */
+    fetch?: typeof fetch;
+    /** When true, the request fails if no token is available. */
+    requireAuth?: boolean;
+    /**
+     * Pre-loaded config to avoid re-reading from disk. Set by
+     * `buildAppContext`, which has already loaded it. (#1311 review P2.)
+     */
+    loadedConfig?: CliConfig;
+}
+
+/**
+ * Find a command on a resource by its CLI-facing name. Returns
+ * `undefined` if not found.
+ */
+export declare function findCommand(resource: CliResource, commandName: string): CommandDefinition | undefined;
+
+/**
+ * Find a resource by slug in the discovery payload. Returns `undefined`
+ * if the slug isn't present.
+ */
+export declare function findResourceBySlug(response: ResourceListResponse, slug: string): CliResource | undefined;
+
+/** Resolve the server URL: env var → config file → `defaultServerUrl`. */
+export declare function getServerUrl(context: CliConfigContext, config?: CliConfig): Promise<string>;
+
+/** Resolve the stored bearer token (env var wins over config). */
+export declare function getStoredToken(context: CliConfigContext, config?: CliConfig): Promise<string | undefined>;
+
+/**
+ * Build the URL the CLI should hit for this command, plus the fetch init
+ * (headers, body) it should pass. Returns enough so callers can stream
+ * the response — they decide how to render it (see `output.ts`).
+ */
+export declare function invokeCommand(options: InvokeOptions): Promise<Response>;
+
+declare interface InvokeOptions {
+    context: CliConfigContext;
+    resource: CliResource;
+    command: CommandDefinition;
+    parsed: ParsedArgs;
+    /** Positional `<id>` argument — only meaningful for item-scope commands. */
+    id?: string;
+    /** Custom fetch (tests). */
+    fetch?: typeof fetch;
+}
+
+/** Read the CLI config file. Missing file → empty config. */
+export declare function loadCliConfig(context: CliConfigContext): Promise<CliConfig>;
+
+/**
+ * Configuration for the bridge.
+ *
+ * Combines the {@link CliConfigContext} (env var + config file resolution)
+ * with the local MCP server identity the bridge advertises to clients.
+ */
+export declare interface McpStdioBridgeOptions extends CliConfigContext {
+    /** MCP server identity advertised to local clients. */
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    /** Override the tools endpoint path. Defaults to `/api/mcp/tools`. */
+    toolsPath?: string;
+    /** Override the call endpoint path. Defaults to `/api/mcp/call`. */
+    callPath?: string;
+    /**
+     * Override fetch implementation (used by tests so we never hit the network).
+     */
+    fetch?: typeof fetch;
+}
+
+declare interface OutputOptions {
+    stdout?: NodeJS.WriteStream | Writable;
+    stderr?: NodeJS.WriteStream | Writable;
+    /**
+     * Override the TTY detection (tests). Defaults to `stdout.isTTY`.
+     */
+    stdoutIsTty?: boolean;
+}
+
+export declare interface ParsedArgs {
+    /** Body to send (JSON serialised, for POST/PUT/PATCH). May be empty. */
+    body: Record<string, unknown>;
+    /** Query string parameters (for GET). May be empty. */
+    query: Record<string, string | string[]>;
+    /** True when the user passed a positional `'<json>'` payload — body is that. */
+    fromPositional: boolean;
+}
+
+declare interface ParserOptions {
+    /** Force-treat schema as unsupported (caller already detected unsupportedness). */
+    positionalOnly?: boolean;
+}
+
+/**
+ * Render the response. Returns the desired exit code.
+ */
+export declare function renderResponse(response: Response, options?: OutputOptions): Promise<RenderResult>;
+
+export declare interface RenderResult {
+    exitCode: number;
+}
+
+/**
+ * JSON request helper that injects the stored bearer token. Returns the
+ * parsed JSON body on success; throws an `Error` with the server's `error`
+ * field (or `HTTP <status>`) on failure.
+ */
+export declare function requestJson<T = unknown>(context: CliConfigContext, path: string, init?: RequestInit, options?: RequestJsonOptions): Promise<T>;
+
+/** Options for `requestJson`. */
+export declare interface RequestJsonOptions {
+    /**
+     * When false, skip sending the Authorization header even if a token is
+     * present. Defaults to true.
+     */
+    auth?: boolean;
+    /**
+     * When true, throw if no token is available and `auth` is not false.
+     * Defaults to false.
+     */
+    requireAuth?: boolean;
+    /** Override the server URL for this request. */
+    serverUrl?: string;
+    /** Override the fetch implementation (tests). */
+    fetch?: typeof fetch;
+    /**
+     * Cap on response body size in bytes. The CLI buffers the full body
+     * before JSON-parsing, so without this cap a misbehaving or malicious
+     * server could OOM the CLI process with a multi-GB payload (auth and
+     * discovery both use this code path). Defaults to 10MB — large enough
+     * for any sensible discovery response, small enough that overflow is
+     * a clear signal something's wrong. Pass `Infinity` to disable.
+     * (#1311 review A4.)
+     */
+    maxResponseBytes?: number;
+    /**
+     * Pre-loaded config to avoid re-reading from disk. Set by callers that
+     * already have it (e.g. `buildAppContext`); leave undefined for the
+     * default behavior of loading per-call. (#1311 review P2.)
+     */
+    loadedConfig?: CliConfig;
+}
+
+export declare type ResourceListResponse = ResourceListResponseBody;
+
+declare interface ResourceListResponseBody {
+    user: {
+        authenticated: boolean;
+        id?: string;
+    };
+    warnings: string[];
+    resources: CliResource_2[];
+}
+
+/**
+ * One-call entry point — instantiate the bridge and connect stdio. Returns
+ * a `Promise<void>` that resolves once the transport disconnects.
+ */
+export declare function runMcpStdioBridge(options: McpStdioBridgeOptions): Promise<void>;
+
+/** Persist a login: writes both serverUrl and token to the config file. */
+export declare function saveAuth(context: CliConfigContext, serverUrl: string, token: string): Promise<void>;
+
+/**
+ * Write the CLI config to disk with 0600 permissions (the token is a bearer
+ * credential — anyone who can read the file can impersonate the user).
+ */
+export declare function saveCliConfig(context: CliConfigContext, config: CliConfig): Promise<void>;
+
+export declare type SchemaSupportStatus = {
+    kind: 'ok';
+} | {
+    kind: 'unsupported';
+    reason: string;
+} | {
+    kind: 'missing';
+};
+
+export { }