@stratabook/mcp 0.2.12 → 0.2.14

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 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.14
+
+- Make `strata-mcp connect` the complete client-neutral trading setup flow:
+  choose limits in Strata, sign once, save the secret locally, and return to a
+  confirmed connected Control Center without environment variables or config
+  editing.
+- Re-running `connect` now rotates an existing local session atomically, and
+  saves the new credential only after both activation and old-key revocation
+  are confirmed.
+
+## 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,27 @@ 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
+```
+
+This opens the client-neutral Strata limit picker, registers the locally
+generated key with one wallet signature, saves the credential privately, and
+returns to the live Control Center. Run the same command again to replace the
+old key atomically; the old key is revoked in the same signed transaction.
+
+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 +70,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,17 @@ 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 to choose limits and register a
+local session with one owner signature; run it again to replace that session
+atomically. 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 +116,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 +223,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

@@ -49,7 +49,7 @@ export declare const STRATA_AGENT_HARNESS: {
         readonly instruction: "When an owner requests a Vault pause or resume and vault.pause is live, prepare the exact transaction with the official SDK, verify that the wallet and requested state are unchanged, then have the owner-configured signer sign and broadcast it externally. Preparation alone does not change state.";
     }, {
         readonly id: "onboard_vault";
-        readonly instruction: "Onboarding is one owner signature, once: register the external session key with vault.setup (only the wallet and the session key are required; one session then trades every market) or simply name the session key on the first vault.deposit, which registers it in the same transaction. Policy fields — expiry, cadence, tolerance, per-asset limits — are optional. Verify every echoed field and the prepared transaction before external owner signing and broadcast; retain the session key only in the owner's signer.";
+        readonly instruction: "Onboarding is one owner signature: register the external session key with vault.setup (only the wallet and the session key are required; one session then trades every market) or simply name the session key on the first vault.deposit, which registers it in the same transaction. Policy fields — expiry, cadence, tolerance, per-asset limits — are optional. Supplying replace_session_public_key atomically revokes the old key while registering the new one. Verify every echoed field and the prepared transaction before external owner signing and broadcast; retain the session key only in the owner's signer.";
     }, {
         readonly id: "fund_vault";
         readonly instruction: "When vault.deposit is live, select an asset from the discovered market and use an exact positive atomic amount. Verify the echoed owner, market, asset, and amount plus the prepared transaction before external owner signing and broadcast.";
@@ -64,7 +64,7 @@ export declare const STRATA_AGENT_HARNESS: {
         readonly instruction: "When vault.policy.manage is live, use blocked mode with no allowed wallets to freeze withdrawals or restricted mode with one to eight exact destination-owner wallets. Verify the echoed mode and complete wallet list before external owner signing and broadcast.";
     }, {
         readonly id: "reconcile_maker_status";
-        readonly instruction: "When mm.status.read is live, read the maker's products by wallet address (public, no signature) before and after any maker action: resting firm orders, the intent budget, live signed quotes, each Strand and Current with its remaining exposure and expiry, oracle health, and armed dead-man guards. Reconcile against what the agent believes it posted; treat missing, expired, or disabled products as not quoting.";
+        readonly instruction: "When mm.status.read is live, read the maker's products by wallet address (public, no signature) before and after any maker action: resting firm orders, live signed quotes, each Strand and Current with its remaining exposure and expiry, oracle health, and armed dead-man guards. Reconcile against what the agent believes it posted; treat missing, expired, or disabled products as not quoting.";
     }, {
         readonly id: "stream_maker_fills";
         readonly instruction: "When mm.fills.stream is live, keep one maker stream open per market through the official SDK by wallet address (public, no signature): start from the maker snapshot, apply only contiguous maker_fill and maker_status events, and recover any gap or reconnect from a fresh snapshot. Reconcile every fill and exposure change against the maker's own state before quoting further.";
@@ -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 the secret locally, choose on-chain limits, and register with one owner signature while the Agents page receives only the public key. Rerunning the command atomically replaces the old session. 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

@@ -141,7 +141,7 @@ export const STRATA_AGENT_HARNESS = {
         },
         {
             "id": "onboard_vault",
-            "instruction": "Onboarding is one owner signature, once: register the external session key with vault.setup (only the wallet and the session key are required; one session then trades every market) or simply name the session key on the first vault.deposit, which registers it in the same transaction. Policy fields — expiry, cadence, tolerance, per-asset limits — are optional. Verify every echoed field and the prepared transaction before external owner signing and broadcast; retain the session key only in the owner's signer."
+            "instruction": "Onboarding is one owner signature: register the external session key with vault.setup (only the wallet and the session key are required; one session then trades every market) or simply name the session key on the first vault.deposit, which registers it in the same transaction. Policy fields — expiry, cadence, tolerance, per-asset limits — are optional. Supplying replace_session_public_key atomically revokes the old key while registering the new one. Verify every echoed field and the prepared transaction before external owner signing and broadcast; retain the session key only in the owner's signer."
         },
         {
             "id": "fund_vault",
@@ -161,7 +161,7 @@ export const STRATA_AGENT_HARNESS = {
         },
         {
             "id": "reconcile_maker_status",
-            "instruction": "When mm.status.read is live, read the maker's products by wallet address (public, no signature) before and after any maker action: resting firm orders, the intent budget, live signed quotes, each Strand and Current with its remaining exposure and expiry, oracle health, and armed dead-man guards. Reconcile against what the agent believes it posted; treat missing, expired, or disabled products as not quoting."
+            "instruction": "When mm.status.read is live, read the maker's products by wallet address (public, no signature) before and after any maker action: resting firm orders, live signed quotes, each Strand and Current with its remaining exposure and expiry, oracle health, and armed dead-man guards. Reconcile against what the agent believes it posted; treat missing, expired, or disabled products as not quoting."
         },
         {
             "id": "stream_maker_fills",
@@ -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 the secret locally, choose on-chain limits, and register with one owner signature while the Agents page receives only the public key. Rerunning the command atomically replaces the old session. 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,27 @@
+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 pairingPageUrl(webBase: string, action: PairingAction, sessionPublicKey: string, callbackUrl: string, existing: Pick<StoredTradingConnection, "owner_wallet" | "session_public_key"> | null): string;
+export declare function runLocalPairing(options: PairingOptions): Promise<void>;

package/dist/src/pairing.js

@@ -0,0 +1,300 @@
+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();
+}
+export function pairingPageUrl(webBase, action, sessionPublicKey, callbackUrl, existing) {
+    const agentUrl = new URL("/agents", pairingWebBase(webBase));
+    agentUrl.searchParams.set("pair", action);
+    agentUrl.searchParams.set("session_public_key", sessionPublicKey);
+    if (existing)
+        agentUrl.searchParams.set("owner_wallet", existing.owner_wallet);
+    if (action === "connect" && existing) {
+        agentUrl.searchParams.set("replace_session_public_key", existing.session_public_key);
+    }
+    agentUrl.searchParams.set("callback", callbackUrl);
+    return agentUrl.toString();
+}
+async function waitForOnChainSession(apiBase, action, ownerWallet, sessionPublicKey, replaceSessionPublicKey) {
+    const deadline = Date.now() + 60_000;
+    let lastState = "unavailable";
+    const stateFor = async (key) => {
+        const query = new URLSearchParams({
+            wallet_address: ownerWallet,
+            session_public_key: key,
+        });
+        const response = await fetch(`${apiBase.replace(/\/$/, "")}/v2/vault/status?${query.toString()}`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+        if (!response.ok) {
+            lastState = `http_${response.status}`;
+            return null;
+        }
+        const body = await response.json();
+        if (body.wallet_address !== ownerWallet)
+            return null;
+        if (!body.session)
+            return "absent";
+        if (body.session.session_public_key !== key || typeof body.session.state !== "string")
+            return null;
+        return body.session.state;
+    };
+    while (Date.now() < deadline) {
+        try {
+            const state = await stateFor(sessionPublicKey);
+            lastState = state ?? lastState;
+            if (action === "disconnect" && state === "absent")
+                return;
+            if (action === "connect" && state === "active") {
+                if (!replaceSessionPublicKey || await stateFor(replaceSessionPublicKey) === "absent")
+                    return;
+                lastState = "old_session_still_active";
+            }
+        }
+        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(sessionPublicKey, state, returnUrl, 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(303, {
+                location: returnUrl,
+                "cache-control": "no-store",
+                "x-content-type-options": "nosniff",
+                "x-frame-options": "DENY",
+            });
+            response.end();
+            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 === "disconnect" && !existing) {
+        process.stdout.write("Strata trading is not connected. Read-only tools remain ready.\n");
+        return;
+    }
+    let generated;
+    if (options.action === "disconnect" && 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 webBase = pairingWebBase(options.webBase ?? DEFAULT_PAIRING_WEB_BASE);
+    const returnUrl = new URL("/agents", webBase);
+    returnUrl.searchParams.set("paired", options.action === "connect" ? "connected" : "revoked");
+    const replaceSessionPublicKey = options.action === "connect"
+        ? existing?.session_public_key ?? null
+        : null;
+    const callback = await waitForPairingCallback(generated.session_public_key, state, returnUrl.toString(), async (ownerWallet) => {
+        await waitForOnChainSession(options.apiBase ?? DEFAULT_API_BASE, options.action, ownerWallet, generated.session_public_key, replaceSessionPublicKey);
+        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 agentUrl = pairingPageUrl(webBase, options.action, generated.session_public_key, callback.callbackUrl, existing);
+    process.stdout.write(`${options.action === "disconnect" ? "Revoke" : replaceSessionPublicKey ? "Replace" : "Connect"} Strata agent access in your browser:\n${agentUrl}\n\n`);
+    if (options.openBrowser !== false)
+        launchBrowser(agentUrl);
+    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/dist/src/server.js

@@ -524,7 +524,7 @@ export async function createStrataMcpServer(options = {}) {
         },
     }, async ({ marketId, walletAddress }) => {
         const response = await platformClient.marketMaking.status(marketId, walletAddress);
-        return toolResult(response, `${response.active_products} active maker products; reconcile intent, Strand, Current, signed-quote, and dead-man state before changing exposure.`);
+        return toolResult(response, `${response.active_products} active maker products; reconcile Strand, Current, signed-quote, and dead-man state before changing exposure.`);
     });
     registerTool("strata_market_making_reputation", {
         title: "Read Strata maker reputation",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stratabook/mcp",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "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.14",
     "zod": "^3.25.76"
   },
   "devDependencies": {