@stratabook/mcp 0.2.12 → 0.2.13

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to the Strata SDKs (`@stratabook/sdk`, `@stratabook/mcp`,
 and the `strata-sdk` Rust crate) are recorded here. Versions move together.
 
+## 0.2.13
+
+- Add `strata-mcp connect`: generate the session secret locally, open the
+  owner-wallet registration page with only its public key, verify activation,
+  and save a mode-0600 local credential. No secret copying, chat, config-file,
+  or environment-variable setup is required.
+- Add `strata-mcp disconnect` for exact-session on-chain revocation followed
+  by local credential removal.
+- Automatically load the private local connection for MCP and `doctor`, while
+  preserving explicit environment variables for managed deployments.
+- Keep read-only tools immediate and client-neutral, and document hosted HTTP,
+  Cursor, Claude Code, Codex, Windsurf, and generic stdio installation.
+
 ## 0.2.12
 
 - Make MCP client-neutral: the primary setup works with any stdio or

package/README.md

@@ -22,8 +22,22 @@ Read-only use needs no wallet, key, autonomy setting, or environment variable:
 npx -y @stratabook/mcp
 ```
 
-Do not paste a session secret into chat. Session setup is optional and appears
-only when the user wants the local MCP to sign trading writes.
+Trading setup is optional. When needed, the local MCP generates its own key,
+opens the owner-wallet page, and saves the secret in a mode-0600 local file.
+The browser and Strata receive only the public key:
+
+```sh
+npx -y @stratabook/mcp connect
+```
+
+There is no secret to paste into chat, no environment-variable screen, and no
+client config to edit after the read-only server is installed. Restart or
+refresh the MCP client after the browser confirms connection. Revoke the exact
+session and delete its local credential with:
+
+```sh
+npx -y @stratabook/mcp disconnect
+```
 
 Generic configuration for Claude Desktop, Cursor, Windsurf, and other
 JSON-config MCP clients:
@@ -51,6 +65,10 @@ Check the whole read-only connection without placing a trade:
 npx -y @stratabook/mcp doctor
 ```
 
+The private credential defaults to `~/.config/strata/mcp.json` on macOS/Linux
+and `%APPDATA%\Strata\mcp.json` on Windows. Override it with
+`STRATA_MCP_CREDENTIALS_FILE` when a managed secret volume is required.
+
 The compact default exposes the tools ordinary users need:
 
 - `strata_markets`, `strata_marks`, `strata_book`, `strata_candles`, `strata_trades`

package/dist/src/cli.js

@@ -8,16 +8,26 @@ import { createStrataMcpServer, probeStrataMcpReadiness } from "./server.js";
 import { sessionAutonomyFromEnv } from "./autonomy.js";
 import { SERVER_VERSION } from "./version.js";
 import { friendlyApiError, humanQuoteAmount, parseToolMode } from "./usability.js";
+import { DEFAULT_PAIRING_WEB_BASE, loadTradingEnvironment, runLocalPairing, tradingCredentialsPath, } from "./pairing.js";
 function parse(argv) {
-    const command = argv[0] === "doctor" ? "doctor" : "serve";
-    const args = command === "doctor" ? argv.slice(1) : argv;
+    const knownCommands = new Set(["doctor", "connect", "disconnect"]);
+    const first = argv[0];
+    const command = first && knownCommands.has(first)
+        ? first
+        : "serve";
+    const args = command === "serve" ? argv : argv.slice(1);
     const values = new Map();
+    let openBrowser = true;
     for (let index = 0; index < args.length; index++) {
         const token = args[index];
         if (token === "--help" || token === "-h") {
             help();
             process.exit(0);
         }
+        if (token === "--no-open") {
+            openBrowser = false;
+            continue;
+        }
         if (!token?.startsWith("--"))
             throw new Error(`unexpected argument: ${token}`);
         const next = args[index + 1];
@@ -43,6 +53,11 @@ function parse(argv) {
         timeoutMs,
         host,
         port,
+        openBrowser,
+        webBase: values.get("web-base") ?? process.env.STRATA_MCP_WEB_BASE ?? DEFAULT_PAIRING_WEB_BASE,
+        ...(values.get("credentials-file") === undefined
+            ? {}
+            : { credentialsFile: values.get("credentials-file") }),
     };
 }
 function boundedInteger(raw, name, min, max) {
@@ -58,6 +73,8 @@ function help() {
 Usage:
   strata-mcp
   strata-mcp doctor
+  strata-mcp connect
+  strata-mcp disconnect
   strata-mcp --transport http [--host localhost] [--port 8787]
 
 Options:
@@ -67,13 +84,16 @@ Options:
   --timeout-ms N           Upstream timeout, 250..60000 (default: 10000)
   --host HOST              HTTP bind host (default: localhost)
   --port N                 HTTP port (default: 8787)
+  --credentials-file PATH  Override the private local trading credential file
+  --no-open                Print the wallet pairing URL without opening a browser
 
 Read-only markets, books, and Sonar quotes work immediately. Run strata-mcp
-doctor to check them. Trading setup is only needed for trading writes; connect
-it at https://stratabook.app/agents. Strata never asks for seed phrases.
+doctor to check them. Run strata-mcp connect once to register a local session
+with the owner wallet; there are no secrets to copy or environment variables
+to edit. Run strata-mcp disconnect to revoke it. Strata never asks for seed phrases.
 `);
 }
-async function runDoctor(options) {
+async function runDoctor(options, sessionEnv) {
     const client = new StrataClient({ apiBase: options.apiBase, timeoutMs: options.timeoutMs });
     process.stdout.write("Strata MCP doctor\n\n");
     try {
@@ -95,10 +115,10 @@ async function runDoctor(options) {
         else {
             process.stdout.write("○ SOL/USDC is not currently listed; quote check skipped\n");
         }
-        const sessionConfigured = Boolean(process.env.STRATA_SESSION_SECRET_KEY && process.env.STRATA_OWNER_WALLET);
+        const sessionConfigured = Boolean(sessionEnv.STRATA_SESSION_SECRET_KEY && sessionEnv.STRATA_OWNER_WALLET);
         process.stdout.write(sessionConfigured
             ? "✓ Trading connection found (no transaction sent)\n"
-            : "○ Trading is not connected; read-only use is ready. Connect later at https://stratabook.app/agents\n");
+            : "○ Trading is not connected; read-only use is ready. Run strata-mcp connect when needed.\n");
     }
     catch (error) {
         if (error instanceof StrataApiError) {
@@ -202,15 +222,27 @@ function safeError(error) {
 }
 async function main() {
     const options = parse(process.argv.slice(2));
+    if (options.command === "connect" || options.command === "disconnect") {
+        await runLocalPairing({
+            action: options.command,
+            webBase: options.webBase,
+            apiBase: options.apiBase,
+            openBrowser: options.openBrowser,
+            ...(options.credentialsFile === undefined ? {} : { credentialsFile: options.credentialsFile }),
+        });
+        return;
+    }
+    const sessionEnv = await loadTradingEnvironment(process.env);
     if (options.command === "doctor") {
-        await runDoctor(options);
+        await runDoctor(options, sessionEnv);
         return;
     }
-    const sessionAutonomy = await sessionAutonomyFromEnv(process.env);
+    const sessionAutonomy = await sessionAutonomyFromEnv(sessionEnv);
     const withSession = sessionAutonomy ? { ...options, sessionAutonomy } : options;
     if (sessionAutonomy) {
         process.stderr.write(`[strata-mcp] session autonomy: ${sessionAutonomy.config.level} `
-            + `(wallet ${sessionAutonomy.ownerWallet.slice(0, 6)}…, session ${sessionAutonomy.signer.publicKey.slice(0, 6)}…)\n`);
+            + `(wallet ${sessionAutonomy.ownerWallet.slice(0, 6)}…, session ${sessionAutonomy.signer.publicKey.slice(0, 6)}…, `
+            + `credentials ${process.env.STRATA_SESSION_SECRET_KEY ? "environment" : tradingCredentialsPath(process.env)})\n`);
     }
     if (withSession.transport === "stdio")
         await runStdio(withSession);

package/dist/src/generated-harness.d.ts

@@ -551,4 +551,4 @@ export declare const STRATA_ACTION_GRAPH: {
     }];
 };
 export declare const STRATA_ACTION_GRAPH_URI = "strata://action-graph/v1";
-export declare const STRATA_AGENT_HARNESS_INSTRUCTIONS = "Strata read-only tools work immediately with no wallet, approval, session key, or environment setup. Call the requested tool directly: use strata_quote for a quote, strata_markets only when the market is unknown, and strata_portfolio for a public account. Do not begin with capability, graph, status, or market discovery unless the requested tool is unavailable, the objective is advanced or ambiguous, or the user asks what Strata supports. Simple MCP tools accept exact human amounts such as 0.1 SOL, 20 USDC, or $20; advanced and SDK interfaces also accept token atoms. Never request or accept a session secret in chat. A session is needed only when the user asks to sign a trading write; if it is missing, strata_trade returns a read-only quote and the single setup link https://stratabook.app/agents. Revoke, withdraw, pause, and policy changes are owner-wallet actions and never use the session signer. Strata Agent Harness 1.0. The action-graph resources are optional references for advanced integrations. The external agent owner controls permission and signer authority. Strata accepts public keys, detached signatures, and signed transactions, never private keys or seed phrases. Check quote bindings, labelled fees, minimum output, price impact, tolerance, and expiry. When portfolio.read is live, read the owner's live Vault portfolio before sizing a write and treat null USD totals as an incomplete valuation, never as zero. When mm.status.read is live, reconcile the owner's maker products and exposure before and after maker actions. For normal Strand or Current operation, prefer strata_market_making_prepare, sign only its prepared transaction externally, then pass its unchanged preparationToken with the signed transaction to strata_market_making_submit_and_wait. Advanced order, TWAP, and execution integrations may use explicit challenge, prepare, verify, sign, and submit flows with idempotency. Stop on ambiguity, sequence gaps, unavailable capabilities, paused markets, inconsistent bindings, expiry, or missing signer authority.";
+export declare const STRATA_AGENT_HARNESS_INSTRUCTIONS = "Strata read-only tools work immediately with no wallet, approval, session key, or environment setup. Call the requested tool directly: use strata_quote for a quote, strata_markets only when the market is unknown, and strata_portfolio for a public account. Do not begin with capability, graph, status, or market discovery unless the requested tool is unavailable, the objective is advanced or ambiguous, or the user asks what Strata supports. Simple MCP tools accept exact human amounts such as 0.1 SOL, 20 USDC, or $20; advanced and SDK interfaces also accept token atoms. Never request or accept a session secret in chat. A session is needed only when the user asks to sign a trading write; if it is missing, strata_trade returns a read-only quote and the single setup link https://stratabook.app/agents. The user can run npx -y @stratabook/mcp connect to generate and store the secret locally while the Agents page receives only its public key. Revoke, withdraw, pause, and policy changes are owner-wallet actions and never use the session signer. Strata Agent Harness 1.0. The action-graph resources are optional references for advanced integrations. The external agent owner controls permission and signer authority. Strata accepts public keys, detached signatures, and signed transactions, never private keys or seed phrases. Check quote bindings, labelled fees, minimum output, price impact, tolerance, and expiry. When portfolio.read is live, read the owner's live Vault portfolio before sizing a write and treat null USD totals as an incomplete valuation, never as zero. When mm.status.read is live, reconcile the owner's maker products and exposure before and after maker actions. For normal Strand or Current operation, prefer strata_market_making_prepare, sign only its prepared transaction externally, then pass its unchanged preparationToken with the signed transaction to strata_market_making_submit_and_wait. Advanced order, TWAP, and execution integrations may use explicit challenge, prepare, verify, sign, and submit flows with idempotency. Stop on ambiguity, sequence gaps, unavailable capabilities, paused markets, inconsistent bindings, expiry, or missing signer authority.";

package/dist/src/generated-harness.js

@@ -789,4 +789,4 @@ export const STRATA_ACTION_GRAPH = {
     ]
 };
 export const STRATA_ACTION_GRAPH_URI = "strata://action-graph/v1";
-export const STRATA_AGENT_HARNESS_INSTRUCTIONS = "Strata read-only tools work immediately with no wallet, approval, session key, or environment setup. Call the requested tool directly: use strata_quote for a quote, strata_markets only when the market is unknown, and strata_portfolio for a public account. Do not begin with capability, graph, status, or market discovery unless the requested tool is unavailable, the objective is advanced or ambiguous, or the user asks what Strata supports. Simple MCP tools accept exact human amounts such as 0.1 SOL, 20 USDC, or $20; advanced and SDK interfaces also accept token atoms. Never request or accept a session secret in chat. A session is needed only when the user asks to sign a trading write; if it is missing, strata_trade returns a read-only quote and the single setup link https://stratabook.app/agents. Revoke, withdraw, pause, and policy changes are owner-wallet actions and never use the session signer. Strata Agent Harness 1.0. The action-graph resources are optional references for advanced integrations. The external agent owner controls permission and signer authority. Strata accepts public keys, detached signatures, and signed transactions, never private keys or seed phrases. Check quote bindings, labelled fees, minimum output, price impact, tolerance, and expiry. When portfolio.read is live, read the owner's live Vault portfolio before sizing a write and treat null USD totals as an incomplete valuation, never as zero. When mm.status.read is live, reconcile the owner's maker products and exposure before and after maker actions. For normal Strand or Current operation, prefer strata_market_making_prepare, sign only its prepared transaction externally, then pass its unchanged preparationToken with the signed transaction to strata_market_making_submit_and_wait. Advanced order, TWAP, and execution integrations may use explicit challenge, prepare, verify, sign, and submit flows with idempotency. Stop on ambiguity, sequence gaps, unavailable capabilities, paused markets, inconsistent bindings, expiry, or missing signer authority.";
+export const STRATA_AGENT_HARNESS_INSTRUCTIONS = "Strata read-only tools work immediately with no wallet, approval, session key, or environment setup. Call the requested tool directly: use strata_quote for a quote, strata_markets only when the market is unknown, and strata_portfolio for a public account. Do not begin with capability, graph, status, or market discovery unless the requested tool is unavailable, the objective is advanced or ambiguous, or the user asks what Strata supports. Simple MCP tools accept exact human amounts such as 0.1 SOL, 20 USDC, or $20; advanced and SDK interfaces also accept token atoms. Never request or accept a session secret in chat. A session is needed only when the user asks to sign a trading write; if it is missing, strata_trade returns a read-only quote and the single setup link https://stratabook.app/agents. The user can run npx -y @stratabook/mcp connect to generate and store the secret locally while the Agents page receives only its public key. Revoke, withdraw, pause, and policy changes are owner-wallet actions and never use the session signer. Strata Agent Harness 1.0. The action-graph resources are optional references for advanced integrations. The external agent owner controls permission and signer authority. Strata accepts public keys, detached signatures, and signed transactions, never private keys or seed phrases. Check quote bindings, labelled fees, minimum output, price impact, tolerance, and expiry. When portfolio.read is live, read the owner's live Vault portfolio before sizing a write and treat null USD totals as an incomplete valuation, never as zero. When mm.status.read is live, reconcile the owner's maker products and exposure before and after maker actions. For normal Strand or Current operation, prefer strata_market_making_prepare, sign only its prepared transaction externally, then pass its unchanged preparationToken with the signed transaction to strata_market_making_submit_and_wait. Advanced order, TWAP, and execution integrations may use explicit challenge, prepare, verify, sign, and submit flows with idempotency. Stop on ambiguity, sequence gaps, unavailable capabilities, paused markets, inconsistent bindings, expiry, or missing signer authority.";

package/dist/src/pairing.d.ts

@@ -0,0 +1,26 @@
+export declare const DEFAULT_PAIRING_WEB_BASE = "https://stratabook.app";
+export interface StoredTradingConnection {
+    readonly schema_version: 1;
+    readonly owner_wallet: string;
+    readonly session_public_key: string;
+    readonly session_secret_key: string;
+    readonly autonomy: "ask" | "limits" | "instant";
+    readonly connected_at_ms: number;
+}
+export type PairingAction = "connect" | "disconnect";
+export interface PairingOptions {
+    readonly action: PairingAction;
+    readonly webBase?: string;
+    readonly openBrowser?: boolean;
+    readonly credentialsFile?: string;
+    readonly apiBase?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly nowMs?: () => number;
+}
+export declare function tradingCredentialsPath(env?: Readonly<Record<string, string | undefined>>, platform?: NodeJS.Platform, home?: string): string;
+export declare function readTradingConnection(path?: string): Promise<StoredTradingConnection | null>;
+export declare function writeTradingConnection(connection: StoredTradingConnection, path?: string): Promise<void>;
+export declare function removeTradingConnection(path?: string): Promise<void>;
+/** Explicit environment variables win; otherwise load the private local file. */
+export declare function loadTradingEnvironment(env?: Readonly<Record<string, string | undefined>>): Promise<Record<string, string | undefined>>;
+export declare function runLocalPairing(options: PairingOptions): Promise<void>;

package/dist/src/pairing.js

@@ -0,0 +1,293 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { DEFAULT_API_BASE, generateSessionKeypair, } from "@stratabook/sdk";
+const PUBLIC_KEY_PATTERN = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+const SECRET_KEY_PATTERN = /^[1-9A-HJ-NP-Za-km-z]{80,90}$/;
+const PAIRING_TIMEOUT_MS = 10 * 60_000;
+export const DEFAULT_PAIRING_WEB_BASE = "https://stratabook.app";
+function validPublicKey(value) {
+    return typeof value === "string" && PUBLIC_KEY_PATTERN.test(value);
+}
+function validSecretKey(value) {
+    return typeof value === "string" && SECRET_KEY_PATTERN.test(value);
+}
+export function tradingCredentialsPath(env = process.env, platform = process.platform, home = homedir()) {
+    const override = env.STRATA_MCP_CREDENTIALS_FILE?.trim();
+    if (override)
+        return resolve(override);
+    if (platform === "win32") {
+        const appData = env.APPDATA?.trim()
+            || join(env.USERPROFILE?.trim() || home, "AppData", "Roaming");
+        return join(appData, "Strata", "mcp.json");
+    }
+    const configRoot = env.XDG_CONFIG_HOME?.trim() || join(home, ".config");
+    return join(configRoot, "strata", "mcp.json");
+}
+export async function readTradingConnection(path = tradingCredentialsPath()) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Strata trading credentials are not valid JSON: ${path}`);
+    }
+    if (!value || typeof value !== "object") {
+        throw new Error(`Strata trading credentials are invalid: ${path}`);
+    }
+    const candidate = value;
+    if (candidate.schema_version !== 1
+        || !validPublicKey(candidate.owner_wallet)
+        || !validPublicKey(candidate.session_public_key)
+        || !validSecretKey(candidate.session_secret_key)
+        || !["ask", "limits", "instant"].includes(candidate.autonomy ?? "")
+        || !Number.isSafeInteger(candidate.connected_at_ms)) {
+        throw new Error(`Strata trading credentials are invalid: ${path}`);
+    }
+    return candidate;
+}
+export async function writeTradingConnection(connection, path = tradingCredentialsPath()) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(connection, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    // `mode` is honored on creation. chmod also tightens a pre-existing file.
+    if (process.platform !== "win32")
+        await chmod(path, 0o600);
+}
+export async function removeTradingConnection(path = tradingCredentialsPath()) {
+    try {
+        await unlink(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+/** Explicit environment variables win; otherwise load the private local file. */
+export async function loadTradingEnvironment(env = process.env) {
+    if (env.STRATA_SESSION_SECRET_KEY || env.STRATA_OWNER_WALLET)
+        return { ...env };
+    const path = tradingCredentialsPath(env);
+    const connection = await readTradingConnection(path);
+    if (!connection)
+        return { ...env };
+    return {
+        ...env,
+        STRATA_OWNER_WALLET: connection.owner_wallet,
+        STRATA_SESSION_PUBLIC_KEY: connection.session_public_key,
+        STRATA_SESSION_SECRET_KEY: connection.session_secret_key,
+        STRATA_AUTONOMY: env.STRATA_AUTONOMY ?? connection.autonomy,
+    };
+}
+function pairingWebBase(raw) {
+    const url = new URL(raw);
+    const local = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+    if (url.protocol !== "https:" && !(local && url.protocol === "http:")) {
+        throw new Error("pairing web base must use HTTPS (or HTTP on localhost)");
+    }
+    url.pathname = "";
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+}
+function launchBrowser(url) {
+    const command = process.platform === "darwin"
+        ? { file: "open", args: [url] }
+        : process.platform === "win32"
+            ? { file: "cmd", args: ["/c", "start", "", url] }
+            : { file: "xdg-open", args: [url] };
+    const child = spawn(command.file, command.args, { detached: true, stdio: "ignore" });
+    child.on("error", () => undefined);
+    child.unref();
+}
+function successHtml(action, wallet) {
+    const connected = action === "connect";
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'">
+<title>Strata agent ${connected ? "connected" : "disconnected"}</title>
+<style>html{color-scheme:dark}body{margin:0;min-height:100vh;display:grid;place-items:center;background:#080b11;color:#e2e8f0;font:15px Inter,system-ui,sans-serif}.card{width:min(520px,calc(100% - 48px));padding:28px;border:1px solid transparent;border-radius:16px;background:linear-gradient(#10141c,#090c12) padding-box,linear-gradient(120deg,#22d3ee,#8b5cf6) border-box;box-shadow:0 22px 80px #0008}h1{margin:0 0 10px;color:white;font-size:24px}p{line-height:1.55;color:#94a3b8}.ok{color:#34d399;font-weight:700}.mono{font-family:ui-monospace,monospace;color:#cbd5e1}</style>
+</head><body><main class="card"><div class="ok">${connected ? "CONNECTED" : "REVOKED"}</div>
+<h1>${connected ? "Your agent can trade" : "Agent access removed"}</h1>
+<p>${connected ? "The session secret was saved only on this computer. Restart or refresh your MCP client, then trade normally." : "The local trading credential has been removed. Read-only Strata tools still work."}</p>
+<p class="mono">Wallet ${wallet.slice(0, 6)}…${wallet.slice(-6)}</p></main></body></html>`;
+}
+async function waitForOnChainSession(apiBase, action, ownerWallet, sessionPublicKey) {
+    const deadline = Date.now() + 60_000;
+    let lastState = "unavailable";
+    while (Date.now() < deadline) {
+        try {
+            const query = new URLSearchParams({
+                wallet_address: ownerWallet,
+                session_public_key: sessionPublicKey,
+            });
+            const response = await fetch(`${apiBase.replace(/\/$/, "")}/v2/vault/status?${query.toString()}`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+            if (response.ok) {
+                const body = await response.json();
+                if (body.wallet_address === ownerWallet) {
+                    lastState = typeof body.session?.state === "string" ? body.session.state : "absent";
+                    const exactSession = body.session?.session_public_key === sessionPublicKey;
+                    if (action === "connect" && exactSession && body.session?.state === "active")
+                        return;
+                    if (action === "disconnect" && (!body.session || (exactSession && body.session.state === "absent")))
+                        return;
+                }
+            }
+            else {
+                lastState = `http_${response.status}`;
+            }
+        }
+        catch (error) {
+            lastState = error instanceof Error ? error.name : "unavailable";
+        }
+        await new Promise((resolveDelay) => setTimeout(resolveDelay, 1_000));
+    }
+    throw new Error(`Strata could not confirm the ${action === "connect" ? "active" : "revoked"} session on-chain `
+        + `(last state: ${lastState}). The local credential was not changed.`);
+}
+async function waitForPairingCallback(action, sessionPublicKey, state, onComplete) {
+    let settle;
+    let reject;
+    const completion = new Promise((resolvePromise, rejectPromise) => {
+        settle = resolvePromise;
+        reject = rejectPromise;
+    });
+    let finished = false;
+    const server = createServer(async (request, response) => {
+        const requestUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+        if (request.method !== "GET" || requestUrl.pathname !== `/complete/${state}`) {
+            response.writeHead(404, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
+            response.end("Not found");
+            return;
+        }
+        if (finished) {
+            response.writeHead(409, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
+            response.end("Pairing already completed");
+            return;
+        }
+        const ownerWallet = requestUrl.searchParams.get("owner_wallet") ?? "";
+        const returnedSession = requestUrl.searchParams.get("session_public_key") ?? "";
+        if (!validPublicKey(ownerWallet) || returnedSession !== sessionPublicKey) {
+            response.writeHead(400, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
+            response.end("Invalid Strata pairing callback");
+            return;
+        }
+        finished = true;
+        try {
+            await onComplete(ownerWallet);
+            response.writeHead(200, {
+                "content-type": "text/html; charset=utf-8",
+                "cache-control": "no-store",
+                "x-content-type-options": "nosniff",
+                "x-frame-options": "DENY",
+            });
+            response.end(successHtml(action, ownerWallet));
+            settle(ownerWallet);
+        }
+        catch (error) {
+            response.writeHead(500, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
+            response.end("Could not save the local Strata connection");
+            reject(error instanceof Error ? error : new Error(String(error)));
+        }
+        finally {
+            server.close();
+        }
+    });
+    server.on("error", (error) => reject(error));
+    await new Promise((resolveListen, rejectListen) => {
+        server.once("error", rejectListen);
+        server.listen(0, "127.0.0.1", () => {
+            server.off("error", rejectListen);
+            resolveListen();
+        });
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        server.close();
+        throw new Error("could not start the local Strata pairing callback");
+    }
+    const timeout = setTimeout(() => {
+        if (finished)
+            return;
+        finished = true;
+        server.close();
+        reject(new Error("Strata pairing timed out after 10 minutes"));
+    }, PAIRING_TIMEOUT_MS);
+    timeout.unref();
+    completion.finally(() => clearTimeout(timeout)).catch(() => undefined);
+    return {
+        callbackUrl: `http://127.0.0.1:${address.port}/complete/${state}`,
+        completion,
+    };
+}
+export async function runLocalPairing(options) {
+    const env = options.env ?? process.env;
+    const path = options.credentialsFile ?? tradingCredentialsPath(env);
+    const existing = await readTradingConnection(path);
+    if (options.action === "connect" && existing) {
+        throw new Error(`Trading is already connected for wallet ${existing.owner_wallet}. `
+            + "Run strata-mcp disconnect before replacing this session.");
+    }
+    if (options.action === "disconnect" && !existing) {
+        process.stdout.write("Strata trading is not connected. Read-only tools remain ready.\n");
+        return;
+    }
+    let generated;
+    if (existing) {
+        generated = existing;
+    }
+    else {
+        const keypair = await generateSessionKeypair();
+        generated = {
+            schema_version: 1,
+            owner_wallet: "",
+            session_public_key: keypair.publicKey,
+            session_secret_key: keypair.secretKey,
+            autonomy: "instant",
+            connected_at_ms: 0,
+        };
+    }
+    const state = randomBytes(24).toString("hex");
+    const callback = await waitForPairingCallback(options.action, generated.session_public_key, state, async (ownerWallet) => {
+        await waitForOnChainSession(options.apiBase ?? DEFAULT_API_BASE, options.action, ownerWallet, generated.session_public_key);
+        if (options.action === "disconnect") {
+            if (existing?.owner_wallet !== ownerWallet) {
+                throw new Error("the revoking wallet does not own this local Strata connection");
+            }
+            await removeTradingConnection(path);
+            return;
+        }
+        await writeTradingConnection({
+            ...generated,
+            owner_wallet: ownerWallet,
+            connected_at_ms: (options.nowMs ?? Date.now)(),
+        }, path);
+    });
+    const webBase = pairingWebBase(options.webBase ?? DEFAULT_PAIRING_WEB_BASE);
+    const agentUrl = new URL("/agents", webBase);
+    agentUrl.searchParams.set("pair", options.action);
+    agentUrl.searchParams.set("session_public_key", generated.session_public_key);
+    agentUrl.searchParams.set("callback", callback.callbackUrl);
+    process.stdout.write(`${options.action === "connect" ? "Connect" : "Revoke"} Strata agent access in your browser:\n${agentUrl.toString()}\n\n`);
+    if (options.openBrowser !== false)
+        launchBrowser(agentUrl.toString());
+    process.stdout.write("Waiting for the owner-wallet signature…\n");
+    const ownerWallet = await callback.completion;
+    process.stdout.write(options.action === "connect"
+        ? `✓ Trading connected for ${ownerWallet}. Credentials saved privately at ${path}.\nRestart or refresh your MCP client.\n`
+        : `✓ Session revoked for ${ownerWallet}. Local trading credentials removed.\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stratabook/mcp",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "Connect AI agents to Strata markets and Sonar quotes with MCP.",
   "type": "module",
   "license": "MIT OR Apache-2.0",
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
-    "@stratabook/sdk": "0.2.12",
+    "@stratabook/sdk": "0.2.13",
     "zod": "^3.25.76"
   },
   "devDependencies": {