@tempoxyz/mercator 0.0.0

package/README.md

@@ -0,0 +1,208 @@
+# `@tempoxyz/mercator`
+
+Install and diagnose the Mercator remote MCP server, desktop plugin, and a session-capable payment
+wallet across supported agent clients.
+
+```sh
+curl -fsSL https://mercator.tempo.xyz/install.sh | sh
+mercator doctor
+```
+
+The installer places the CLI under `~/.local`, links `mercator` into `~/.local/bin`, and launches
+the same interactive setup flow. Pass CLI arguments after `sh -s --`, for example:
+
+```sh
+curl -fsSL https://mercator.tempo.xyz/install.sh | sh -s -- --client codex
+```
+
+## Setup flow
+
+```mermaid
+flowchart LR
+    START["Start setup"] --> DETECT["Detect supported clients"]
+    DETECT --> PLUGIN["Bootstrap local desktop plugin"]
+    PLUGIN -->|Agent CLI found| CONFIGURE["Install Mercator MCP entry"]
+    PLUGIN -->|No agent CLI| GUIDANCE
+    CONFIGURE --> GUIDANCE["Update managed guidance"]
+    GUIDANCE --> WALLET{"Ready payment runtime?"}
+    WALLET -->|Yes| VERIFY["Run readiness checks"]
+    WALLET -->|No| ONBOARD["Create local wallet or connect Tempo Wallet"]
+    ONBOARD --> VERIFY
+```
+
+Supported clients:
+
+- Codex
+- Claude Code
+- Gemini CLI
+- Cursor
+- VS Code
+- Windsurf
+- Cline
+- Continue
+- OpenClaw
+- Hermes
+
+Normal setup always bootstraps the bundled [Mercator plugin](../../plugins/mercator) into Codex's
+user-local plugin index. Nothing is published, and users do not need to create or manage a
+marketplace. The plugin connects Codex or ChatGPT desktop directly to the production Mercator MCP
+server without requiring the Codex CLI. Restart ChatGPT desktop after installation. Use
+`--no-plugin` for a CLI-only installation, such as CI or a headless server.
+
+Selection options:
+
+| Option | Behavior |
+| --- | --- |
+| No subcommand | Bootstrap the local plugin and run interactive `setup` |
+| Picker | Show detected clients; select several entries or `all` |
+| `--client <name>` | Configure one named client; repeatable |
+| `--all` | Configure every supported client non-interactively |
+| `--dry-run` | Preview configuration changes |
+| `--force` | Recreate Mercator registrations and refresh managed guidance |
+| `--no-plugin` | Skip local desktop plugin installation |
+| `--no-agents` | Skip Codex `AGENTS.md` guidance |
+| `--remove-agents` | Remove installed Codex guidance |
+
+Setup guarantees:
+
+- Reuses matching existing configuration safely.
+- Serializes plugin index updates and preserves unrelated local plugins.
+- Shows a rotating [adamsky/globe](https://github.com/adamsky/globe) with live setup progress.
+- Keeps the globe active while the interactive client picker is open.
+- `--force` never removes or recreates wallets, keys, accounts, balances, sessions, or shared MPP
+  plugins.
+- Wallet and native payment checks remain read-only during forced setup.
+
+Example:
+
+```sh
+mercator setup --client codex --force
+```
+
+## Codex guidance
+
+Codex setup maintains a bounded block in the active global `AGENTS.md`:
+
+- Explains when to use Mercator.
+- Requires quote and budget approval before paid execution.
+- Excludes local files and repository work.
+- Preserves content outside `mercator:begin` and `mercator:end` HTML comments.
+- Leaves an existing `AGENTS.override.md` untouched and reports when it shadows the guidance.
+- Applies new guidance to the next Codex session.
+
+Mercator always manages persistent `AGENTS.md`; use `--no-agents` to skip installation or
+`--remove-agents` to remove the managed block.
+
+## Payment runtime selection
+
+Mercator uses one active payment wallet. `mercator wallet connect` and `mercator wallet create`
+record that selection. Existing installations without an active selection continue using their
+Tempo Wallet credentials when present, otherwise their local disk wallet.
+
+| Runtime | Paid-request path | Session behavior |
+| --- | --- | --- |
+| Local disk wallet | `mercator submit` | Uses Mercator-owned Accounts SDK storage |
+| Tempo Wallet | `mercator submit` | Uses a scoped access key authorized through Accounts |
+| OpenClaw | Native `mpp_fetch` | Uses official `openclaw-mpp` integration |
+| Hermes | Native `mpp_fetch` | Uses official `hermes-mpp` integration |
+
+Mercator requires neither the Tempo Wallet CLI nor the MPPX CLI. Connecting or creating an unfunded
+wallet opens Mercator's MACH funding page with its address selected. The page offers fixed amounts
+and redirects to Stripe-hosted Checkout with card and Apple Pay support. Run `mercator wallet fund`
+to open it again later.
+
+OpenClaw and Hermes setup:
+
+- Installs or verifies the official
+  [openclaw-mpp](https://github.com/tempoxyz/openclaw-mpp) or
+  [hermes-mpp](https://github.com/tempoxyz/hermes-mpp) integration.
+- Preserves existing Hermes allowed origins before adding Mercator.
+
+## Wallet onboarding
+
+Run wallet setup separately:
+
+```sh
+mercator wallet
+mercator wallet connect
+mercator wallet create
+mercator wallet status
+mercator wallet balance
+mercator wallet fund
+```
+
+With no active wallet, `mercator wallet` asks whether to connect an existing wallet or create one
+on this machine. `wallet connect` opens the Accounts SDK device flow and stores only its Mercator
+access key locally. Local-wallet private material, connected-wallet access keys, and the active
+selection share the Accounts SDK filesystem store at `~/.mercator/wallet.json`, secured with
+user-only file permissions.
+
+`mercator wallet status` inspects readiness without onboarding. `mercator wallet`,
+`mercator wallet balance`, and `mercator wallet fund` report the active wallet's balances. Creating
+or connecting an unfunded wallet opens Mercator's card onramp; inspecting an existing wallet does
+not.
+
+## Paid job submission
+
+```mermaid
+flowchart LR
+    MCP["MCP: discover + quote"] --> REST["POST /v1/jobs"]
+    REST --> PAYMENT["Mercator wallet"]
+    PAYMENT --> POLL["MCP or REST: poll result"]
+```
+
+Recommended path:
+
+- Use MCP for discovery, quoting, and result polling.
+- Use the bounded `mercator submit` handoff returned by `create_job`.
+- The REST endpoint offers both `tempo/session` and `tempo/charge`.
+- Some MCP harnesses cannot answer the payment-required protocol error from `create_job`.
+- Use `mpp_fetch` in OpenClaw or Hermes.
+- Other clients use the same Mercator wallet created during setup.
+
+## Diagnostics
+
+`doctor` performs read-only checks:
+
+- MCP transport.
+- Six-tool contract.
+- Free service discovery.
+- Unsigned Mercator session challenge.
+- Local wallet session capability.
+- Local plugin path, installed and expected versions, registration state, and desktop restart
+  requirement.
+
+Plugin state is advisory so `--no-plugin` installations remain healthy. Funding is reported
+separately from session capability. Paid execution remains `not_verified`.
+
+## Uninstall
+
+```sh
+mercator uninstall --client codex
+mercator uninstall --client openclaw --client hermes
+mercator uninstall --dry-run
+mercator uninstall
+```
+
+Uninstall behavior:
+
+- Removes only the `mercator` MCP entry, CLI-managed local plugin bundle and registration, and
+  installer-managed Codex guidance.
+- Preserves other MCP servers, local plugin entries, and user instructions.
+- Preserves wallets, keys, balances, sessions, and shared MPP plugins.
+- `--dry-run` previews removal.
+- A scoped uninstall removes the plugin only for `--client codex`; an unscoped uninstall removes it
+  with all other Mercator integrations.
+- VS Code removal covers the default user profile; use **MCP: Open User Configuration** for other
+  profiles.
+
+## Command discovery
+
+```sh
+mercator clients
+mercator --help
+mercator --llms
+```
+
+The CLI uses Incur for validated options, generated help, machine-readable manifests, structured
+errors, shell completions, and agent integrations.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,11 @@
+# Third-party notices
+
+## globe
+
+The CLI's terminal globe frames were generated using
+[adamsky/globe](https://github.com/adamsky/globe) commit
+`b0d2eb545672c52a8e6c6fa13faf4ec3c9174b01` and its built-in Earth texture.
+
+Copyright (c) 2022 Adam Kelly. Licensed under the GNU General Public License v3.0.
+The Mercator source distribution contains the generated frames and identifies the generating
+source in `src/globe-frames.ts`.

package/dist/agents.d.ts

@@ -0,0 +1,26 @@
+/** Opening boundary for installer-managed Mercator guidance. */
+export declare const MERCATOR_AGENTS_BEGIN = "<!-- mercator:begin \u2014 managed by mercator-cli; edits inside will be overwritten -->";
+/** Closing boundary for installer-managed Mercator guidance. */
+export declare const MERCATOR_AGENTS_END = "<!-- mercator:end -->";
+/** Durable, budget-aware activation guidance installed for Codex. */
+export declare const MERCATOR_AGENTS_BLOCK = "<!-- mercator:begin \u2014 managed by mercator-cli; edits inside will be overwritten -->\n## Mercator\n\nMercator is an optional gateway for fresh external data and API actions.\n\n- Consider Mercator when a task needs research, extraction, enrichment, social, maps, travel, communications, media, financial, or on-chain data and no installed direct tool is a better fit.\n- Search with `search_services` using the user's complete intended outcome. Discovery and `quote_plan` are free.\n- Before paid execution, show the quoted total and get approval unless the user already supplied a sufficient budget. Never exceed that budget.\n- Once approved, complete the workflow instead of merely naming a service: call `create_job` once with a stable idempotency key, then poll `get_job`. Never create another job to check its status.\n- Do not use Mercator for local files, repository work, reasoning over supplied content, or when the user forbids external or paid services.\n- Never request or expose private keys or provider credentials.\n<!-- mercator:end -->";
+/** Options controlling where and whether Codex guidance is written. */
+export type CodexAgentsInstallOptions = {
+    codexHome?: string;
+    dryRun?: boolean;
+};
+/** Result of planning or applying the managed Codex guidance block. */
+export type CodexAgentsInstallResult = {
+    path: string;
+    shadowed: boolean;
+    state: 'created' | 'current' | 'planned' | 'updated';
+};
+/** Result of planning or removing managed Codex guidance. */
+export type CodexAgentsRemoveResult = {
+    paths: string[];
+    state: 'missing' | 'planned' | 'removed';
+};
+/** Installs or refreshes Mercator guidance in persistent global Codex instructions. */
+export declare function installCodexAgents(options?: CodexAgentsInstallOptions): Promise<CodexAgentsInstallResult>;
+/** Removes every installer-managed Mercator block from global Codex instructions. */
+export declare function removeCodexAgents(options?: CodexAgentsInstallOptions): Promise<CodexAgentsRemoveResult>;

package/dist/agents.js

@@ -0,0 +1,152 @@
+import { lstat, mkdir, readFile, realpath, rename, stat, unlink, writeFile, } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** Opening boundary for installer-managed Mercator guidance. */
+export const MERCATOR_AGENTS_BEGIN = '<!-- mercator:begin — managed by mercator-cli; edits inside will be overwritten -->';
+/** Closing boundary for installer-managed Mercator guidance. */
+export const MERCATOR_AGENTS_END = '<!-- mercator:end -->';
+/** Durable, budget-aware activation guidance installed for Codex. */
+export const MERCATOR_AGENTS_BLOCK = `${MERCATOR_AGENTS_BEGIN}
+## Mercator
+
+Mercator is an optional gateway for fresh external data and API actions.
+
+- Consider Mercator when a task needs research, extraction, enrichment, social, maps, travel, communications, media, financial, or on-chain data and no installed direct tool is a better fit.
+- Search with \`search_services\` using the user's complete intended outcome. Discovery and \`quote_plan\` are free.
+- Before paid execution, show the quoted total and get approval unless the user already supplied a sufficient budget. Never exceed that budget.
+- Once approved, complete the workflow instead of merely naming a service: call \`create_job\` once with a stable idempotency key, then poll \`get_job\`. Never create another job to check its status.
+- Do not use Mercator for local files, repository work, reasoning over supplied content, or when the user forbids external or paid services.
+- Never request or expose private keys or provider credentials.
+${MERCATOR_AGENTS_END}`;
+/** Installs or refreshes Mercator guidance in persistent global Codex instructions. */
+export async function installCodexAgents(options = {}) {
+    const codexHome = options.codexHome ?? process.env.CODEX_HOME ?? join(homedir(), '.codex');
+    const target = await readAgentsFile(join(codexHome, 'AGENTS.md'));
+    const override = await readOptionalFile(join(codexHome, 'AGENTS.override.md'));
+    const shadowed = Boolean(override?.trim());
+    const content = mergeManagedBlock(target.content);
+    if (content === target.content) {
+        return { path: target.path, shadowed, state: 'current' };
+    }
+    if (options.dryRun)
+        return { path: target.path, shadowed, state: 'planned' };
+    await writeAtomically(target.writePath, content, target.mode);
+    return {
+        path: target.path,
+        shadowed,
+        state: target.exists ? 'updated' : 'created',
+    };
+}
+/** Removes every installer-managed Mercator block from global Codex instructions. */
+export async function removeCodexAgents(options = {}) {
+    const codexHome = options.codexHome ?? process.env.CODEX_HOME ?? join(homedir(), '.codex');
+    const targets = await Promise.all(['AGENTS.md', 'AGENTS.override.md'].map(async (name) => {
+        const target = await readAgentsFile(join(codexHome, name));
+        return { ...target, content: removeManagedBlock(target.content) };
+    }));
+    const changed = targets.filter((target) => target.content !== target.original);
+    if (changed.length === 0)
+        return { paths: [], state: 'missing' };
+    const paths = changed.map((target) => target.path);
+    if (options.dryRun)
+        return { paths, state: 'planned' };
+    await Promise.all(changed.map(async (target) => {
+        if (target.content.trim().length > 0 || target.symlink) {
+            await writeAtomically(target.writePath, target.content, target.mode);
+        }
+        else {
+            await unlink(target.path);
+        }
+    }));
+    return { paths, state: 'removed' };
+}
+function mergeManagedBlock(existing) {
+    const managed = managedBlockRange(existing);
+    if (managed) {
+        return `${existing.slice(0, managed.begin)}${MERCATOR_AGENTS_BLOCK}${existing.slice(managed.end)}`;
+    }
+    if (existing.length === 0)
+        return `${MERCATOR_AGENTS_BLOCK}\n`;
+    const separator = existing.endsWith('\n\n')
+        ? ''
+        : existing.endsWith('\n')
+            ? '\n'
+            : '\n\n';
+    return `${existing}${separator}${MERCATOR_AGENTS_BLOCK}\n`;
+}
+function removeManagedBlock(existing) {
+    const managed = managedBlockRange(existing);
+    if (!managed)
+        return existing;
+    const before = existing.slice(0, managed.begin).trimEnd();
+    const after = existing.slice(managed.end).trimStart();
+    if (before && after)
+        return `${before}\n\n${after}`;
+    if (before)
+        return `${before}\n`;
+    return after;
+}
+function managedBlockRange(existing) {
+    const begin = existing.indexOf(MERCATOR_AGENTS_BEGIN);
+    const end = existing.indexOf(MERCATOR_AGENTS_END);
+    if ((begin === -1) !== (end === -1)) {
+        throw new Error('Mercator guidance has an incomplete managed boundary; repair it before rerunning setup.');
+    }
+    if (begin === -1)
+        return undefined;
+    if (end < begin ||
+        existing.indexOf(MERCATOR_AGENTS_BEGIN, begin + 1) !== -1 ||
+        existing.indexOf(MERCATOR_AGENTS_END, end + 1) !== -1) {
+        throw new Error('Mercator guidance has ambiguous managed boundaries; repair them before rerunning setup.');
+    }
+    return { begin, end: end + MERCATOR_AGENTS_END.length };
+}
+async function readAgentsFile(path) {
+    const link = await readOptionalLink(path);
+    const content = await readOptionalFile(path);
+    if (link?.isSymbolicLink() && content === undefined) {
+        throw new Error(`Cannot update broken AGENTS.md symlink: ${path}`);
+    }
+    const exists = content !== undefined;
+    const writePath = exists ? await realpath(path) : path;
+    const mode = exists ? (await stat(path)).mode & 0o777 : undefined;
+    return {
+        content: content ?? '',
+        exists,
+        mode,
+        original: content ?? '',
+        path,
+        symlink: Boolean(link?.isSymbolicLink()),
+        writePath,
+    };
+}
+async function readOptionalLink(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return undefined;
+        throw error;
+    }
+}
+async function readOptionalFile(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return undefined;
+        throw error;
+    }
+}
+function isMissingFile(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+async function writeAtomically(path, content, mode = 0o600) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, content, { encoding: 'utf8', mode });
+    await rename(temporary, path);
+}
+//# sourceMappingURL=agents.js.map

package/dist/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from './index.js';
+process.exitCode = await run(process.argv.slice(2));
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAA;AAEhC,OAAO,CAAC,QAAQ,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA"}

package/dist/client-selection.d.ts

@@ -0,0 +1,13 @@
+import type { ClientId } from './clients.js';
+import { type GlobeAnimation, startMercatorGlobe } from './globe.js';
+type ClientSelectionStreams = {
+    readonly animateGlobe?: boolean;
+    readonly globe?: GlobeAnimation;
+    readonly input: NodeJS.ReadableStream;
+    readonly interactive: boolean;
+    readonly output: NodeJS.WritableStream;
+    readonly startGlobe?: typeof startMercatorGlobe;
+};
+/** Selects detected clients interactively, or requires explicit clients outside a TTY. */
+export declare function selectClients(clients: readonly ClientId[], overrides?: Partial<ClientSelectionStreams>): Promise<ClientId[]>;
+export {};

package/dist/client-selection.js

@@ -0,0 +1,97 @@
+import { createInterface } from 'node:readline/promises';
+import { startMercatorGlobe } from './globe.js';
+const CLIENT_LABELS = {
+    claude: 'Claude Code',
+    cline: 'Cline',
+    codex: 'Codex',
+    continue: 'Continue',
+    cursor: 'Cursor',
+    gemini: 'Gemini CLI',
+    hermes: 'Hermes',
+    openclaw: 'OpenClaw',
+    vscode: 'VS Code',
+    windsurf: 'Windsurf',
+};
+const defaultStreams = () => ({
+    animateGlobe: Boolean(process.stdout.isTTY) &&
+        process.env.CI === undefined &&
+        process.env.TERM !== 'dumb',
+    input: process.stdin,
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    output: process.stdout,
+    startGlobe: startMercatorGlobe,
+});
+/** Selects detected clients interactively, or requires explicit clients outside a TTY. */
+export async function selectClients(clients, overrides = {}) {
+    const streams = { ...defaultStreams(), ...overrides };
+    if (clients.length === 0) {
+        throw new Error('No supported clients detected. Run mercator setup --client <client>.');
+    }
+    const onlyClient = clients.length === 1 ? clients[0] : undefined;
+    if (onlyClient !== undefined) {
+        return [onlyClient];
+    }
+    if (!streams.interactive) {
+        throw new Error(`Multiple clients detected (${clients.join(', ')}). Run mercator setup --client <client>.`);
+    }
+    const ownsGlobe = streams.globe === undefined;
+    if (ownsGlobe)
+        streams.output.write('\n');
+    const globe = streams.globe ??
+        (streams.startGlobe ?? startMercatorGlobe)(streams.output, {
+            animate: streams.animateGlobe ?? false,
+        });
+    const write = (value) => {
+        streams.output.write(value);
+        globe.addLinesBelow(value.match(/\n/g)?.length ?? 0);
+    };
+    write('\nSelect clients to configure:\n\n');
+    const indexWidth = String(clients.length).length;
+    const labelWidth = Math.max(...clients.map((client) => CLIENT_LABELS[client].length));
+    clients.forEach((client, index) => {
+        const number = String(index + 1).padStart(indexWidth);
+        const label = CLIENT_LABELS[client].padEnd(labelWidth);
+        write(`  ${number}. ${label}  (${client})\n`);
+    });
+    write('\nManual mode: mercator setup --client <client> (repeat --client as needed)\n\n');
+    const readline = createInterface({
+        input: streams.input,
+        output: streams.output,
+        terminal: false,
+    });
+    try {
+        write('Selection (numbers, names, or all): ');
+        for await (const line of readline) {
+            globe.addLinesBelow(1);
+            const answer = line.trim().toLowerCase();
+            if (answer === 'a' || answer === 'all')
+                return [...clients];
+            const selected = answer
+                .split(',')
+                .map((value) => value.trim())
+                .filter(Boolean)
+                .map((value) => {
+                const selectedIndex = Number.parseInt(value, 10) - 1;
+                return /^\d+$/.test(value)
+                    ? clients[selectedIndex]
+                    : clients.find((client) => client === value);
+            });
+            if (selected.length > 0 && selected.every((client) => client !== undefined)) {
+                return [...new Set(selected)];
+            }
+            write(`Choose 1-${clients.length}, comma-separated client names, or all.\nSelection (numbers, names, or all): `);
+        }
+    }
+    catch (error) {
+        throw new Error('Client selection cancelled. Run mercator setup --client <client>.', {
+            cause: error,
+        });
+    }
+    finally {
+        readline.close();
+        if (ownsGlobe)
+            await globe.stop();
+    }
+    throw new Error('Client selection cancelled. Run mercator setup --client <client>.');
+}
+//# sourceMappingURL=client-selection.js.map

package/dist/client-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-selection.js","sourceRoot":"","sources":["../src/client-selection.ts"],"names":[],"mappings":"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"}

package/dist/clients.d.ts

@@ -0,0 +1,70 @@
+import { type CommandResult } from './command.js';
+export declare const Client: {
+    readonly Claude: "claude";
+    readonly Cline: "cline";
+    readonly Codex: "codex";
+    readonly Continue: "continue";
+    readonly Cursor: "cursor";
+    readonly Gemini: "gemini";
+    readonly Hermes: "hermes";
+    readonly OpenClaw: "openclaw";
+    readonly VsCode: "vscode";
+    readonly Windsurf: "windsurf";
+};
+export type ClientId = (typeof Client)[keyof typeof Client];
+type CommandPlan = {
+    args: string[];
+    check?: CommandCheck;
+    command: string;
+    kind: 'command';
+    undo: string;
+};
+type CommandCheck = {
+    args: string[];
+    command: string;
+    serverName?: string;
+    url: string;
+};
+type FilePlan = {
+    config: Record<string, unknown>;
+    kind: 'file';
+    path: string;
+    undo: string;
+};
+export type SetupPlan = CommandPlan | FilePlan;
+/** A precise, client-specific operation for removing the Mercator MCP registration. */
+export type RemovalPlan = {
+    args: string[];
+    command: string;
+    kind: 'command';
+} | {
+    kind: 'file';
+    path: string;
+    serverContainer: 'mcpServers' | 'servers';
+} | {
+    instructions: string;
+    kind: 'manual';
+};
+export type ConfigurationState = 'current' | 'different' | 'missing' | 'unknown';
+type RunCheck = (check: CommandCheck) => Promise<CommandResult>;
+export declare const CLIENT_IDS: ("claude" | "cline" | "codex" | "continue" | "cursor" | "gemini" | "hermes" | "openclaw" | "vscode" | "windsurf")[];
+export declare function setupPlan(client: ClientId, url: string, options?: {
+    cwd?: string;
+    home?: string;
+}): SetupPlan;
+/** Builds a conservative removal plan that never includes wallet state. */
+export declare function removalPlan(client: ClientId, options?: {
+    cwd?: string;
+    home?: string;
+    platform?: NodeJS.Platform;
+}): RemovalPlan;
+export declare function configurationState(plan: SetupPlan, runCheck?: RunCheck): Promise<ConfigurationState>;
+export declare function installedClients(isAvailable?: (command: string) => Promise<boolean>): Promise<ClientId[]>;
+export declare function mergeConfigFile(plan: FilePlan): Promise<void>;
+/** Removes only the Mercator server entry while preserving the rest of the file. */
+export declare function removeConfigFile(plan: Extract<RemovalPlan, {
+    kind: 'file';
+}>, options?: {
+    dryRun?: boolean;
+}): Promise<'missing' | 'planned' | 'removed'>;
+export {};