@stratabook/mcp 0.2.10 → 0.2.12

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 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.12
+
+- Make MCP client-neutral: the primary setup works with any stdio or
+  Streamable HTTP MCP host; Codex is only one optional client example.
+- Replace the forced discovery preamble with direct read-only tool use and a
+  compact 12-tool default. `--mode advanced` retains the complete protocol.
+- Accept exact human quote and trade amounts such as `0.1 SOL`, `20 USDC`, and
+  `$20`, resolving market labels and decimals without floating point.
+- Add progressive `strata_trade`, `strata-mcp doctor`, one safe transient quote
+  retry, and plain next steps for common failures.
+
+## 0.2.11
+
+- Consume the exact TypeScript SDK 0.2.11 release containing the installed
+  maker-conformance CLI entrypoint fix.
+- Make the zero-credential read-only path explicit in MCP initialization:
+  markets, books, marks, candles, trades, quotes, public portfolios, and maker
+  reads work immediately. Agents must not request session secrets in chat or
+  begin write onboarding unless the user asks to trade.
+
 ## 0.2.10
 
 - Consume the matching SDK conformance release. The safe deployment gate now

package/README.md

@@ -1,21 +1,32 @@
 # Strata MCP
 
-Official capability-gated MCP access to Strata and Sonar. The server delegates
-to `@stratabook/sdk`: it follows the live capability catalog and contains no
-separate quote or execution logic.
+Official MCP access to Strata and Sonar for every MCP-compatible client. It is
+not tied to Codex, Claude, Cursor, or any other host. The server delegates to
+`@stratabook/sdk` and follows Strata's live public policy.
 
 The official hosted endpoint currently exposes market, exact-output, and
 asset-to-asset Sonar quotes, together with quote-bound execution tools.
-Capability gating is a runtime safety check so clients stop if policy changes;
-it does **not** mean quotes are inactive.
+"Capability gated" simply means a tool disappears if Strata disables that
+operation live. It does **not** mean quotes need activation or user setup.
+
+The default tool mode is deliberately compact. Agents call the requested tool
+directly instead of burning discovery calls before a quote. Use
+`--mode advanced` (or `STRATA_MCP_MODE=advanced`) only when an integration
+needs the explicit challenge / prepare / submit protocol tools.
 
 ## Local stdio
 
+Read-only use needs no wallet, key, autonomy setting, or environment variable:
+
 ```sh
 npx -y @stratabook/mcp
 ```
 
-Example client configuration:
+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.
+
+Generic configuration for Claude Desktop, Cursor, Windsurf, and other
+JSON-config MCP clients:
 
 ```json
 {
@@ -28,7 +39,28 @@ Example client configuration:
 }
 ```
 
-The tools currently available are:
+Codex happens to support a one-line client-specific installer:
+
+```sh
+codex mcp add strata -- npx -y @stratabook/mcp
+```
+
+Check the whole read-only connection without placing a trade:
+
+```sh
+npx -y @stratabook/mcp doctor
+```
+
+The compact default exposes the tools ordinary users need:
+
+- `strata_markets`, `strata_marks`, `strata_book`, `strata_candles`, `strata_trades`
+- `strata_quote` — accepts `0.1 SOL`, `20 USDC`, or `$20`; token atoms remain optional
+- `strata_portfolio` and `strata_market_making_status`
+- `strata_trade` — returns a live quote when trading is not connected, with one setup link; follows the user's session limits when connected
+- `strata_market_making_prepare` and `strata_market_making_submit_and_wait`
+- `strata_autonomy` — reports whether optional trading is connected and the user's limits
+
+Advanced mode additionally exposes the complete protocol surface, including:
 
 - `strata_capabilities`
 - `strata_action_graph`
@@ -71,7 +103,8 @@ The tools currently available are:
 - `strata_order_submit`, when `orders.submit` is enabled for MCP
 - `strata_order_status`, when `orders.submit` is enabled for MCP
 
-Every initialization response carries the compact Strata Agent Harness. The
+Every initialization response carries the compact Strata Agent Harness. It
+instructs an agent to call normal read tools directly. The
 server also publishes the complete harness as the
 `strata://agent-harness/v1` resource and provides a `strata_start` prompt for
 applying it to one concrete objective.
@@ -147,7 +180,9 @@ bounded TWAP placement or cancellation, or atomic place, cancel, cancel-all,
 replace, or bounded batch order controls, and
 submit the externally signed result. It accepts
 public keys, detached signatures, and signed transactions, never private keys,
-seed phrases, or wallet secrets. Amounts are token atoms encoded as base-10
+seed phrases, or wallet secrets. Simple quote and trade tools accept exact
+decimal strings with their symbol; conversion never uses floating-point
+arithmetic. Advanced protocol fields remain token atoms encoded as base-10
 strings.
 
 Quotes default to zero tolerance. `maximumToleranceBps` is the agent's own

package/dist/src/cli.js

@@ -2,22 +2,25 @@
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { DEFAULT_API_BASE } from "@stratabook/sdk";
+import { DEFAULT_API_BASE, StrataApiError, StrataClient } from "@stratabook/sdk";
 import { STRATA_ACTION_GRAPH, STRATA_AGENT_HARNESS, } from "./generated-harness.js";
 import { createStrataMcpServer, probeStrataMcpReadiness } from "./server.js";
 import { sessionAutonomyFromEnv } from "./autonomy.js";
 import { SERVER_VERSION } from "./version.js";
+import { friendlyApiError, humanQuoteAmount, parseToolMode } from "./usability.js";
 function parse(argv) {
+    const command = argv[0] === "doctor" ? "doctor" : "serve";
+    const args = command === "doctor" ? argv.slice(1) : argv;
     const values = new Map();
-    for (let index = 0; index < argv.length; index++) {
-        const token = argv[index];
+    for (let index = 0; index < args.length; index++) {
+        const token = args[index];
         if (token === "--help" || token === "-h") {
             help();
             process.exit(0);
         }
         if (!token?.startsWith("--"))
             throw new Error(`unexpected argument: ${token}`);
-        const next = argv[index + 1];
+        const next = args[index + 1];
         if (!next || next.startsWith("--"))
             throw new Error(`${token} requires a value`);
         values.set(token.slice(2), next);
@@ -33,7 +36,9 @@ function parse(argv) {
     if (!/^[a-zA-Z0-9.:[\]-]+$/.test(host))
         throw new Error("host is invalid");
     return {
+        command,
         transport,
+        toolMode: parseToolMode(values.get("mode") ?? process.env.STRATA_MCP_MODE),
         apiBase: values.get("api-base") ?? process.env.STRATA_API_BASE ?? DEFAULT_API_BASE,
         timeoutMs,
         host,
@@ -52,20 +57,56 @@ function help() {
 
 Usage:
   strata-mcp
+  strata-mcp doctor
   strata-mcp --transport http [--host localhost] [--port 8787]
 
 Options:
   --transport stdio|http   Local stdio by default; Streamable HTTP for hosting
+  --mode simple|advanced   Compact direct tools (default) or full protocol tools
   --api-base URL           Strata public API (default: ${DEFAULT_API_BASE})
   --timeout-ms N           Upstream timeout, 250..60000 (default: 10000)
   --host HOST              HTTP bind host (default: localhost)
   --port N                 HTTP port (default: 8787)
 
-This server exposes capability-gated quote and execution operations. The external
-agent owner controls permission and signing. Strata accepts public keys,
-signatures, and signed transactions, never private keys or seed phrases.
+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.
 `);
 }
+async function runDoctor(options) {
+    const client = new StrataClient({ apiBase: options.apiBase, timeoutMs: options.timeoutMs });
+    process.stdout.write("Strata MCP doctor\n\n");
+    try {
+        const capabilities = await client.capabilities();
+        process.stdout.write(`✓ Public API connected (contract ${capabilities.contract_version})\n`);
+        const response = await client.markets();
+        const ready = response.markets.filter((market) => market.ready);
+        process.stdout.write(`✓ ${ready.length} read-only markets available\n`);
+        const solUsdc = ready.find((market) => market.label.toUpperCase() === "SOL/USDC");
+        if (solUsdc) {
+            const amount = humanQuoteAmount(ready, solUsdc.label, "sell", "0.01 SOL");
+            const quote = await client.quote({
+                market: solUsdc.label,
+                side: "sell",
+                amountInAtoms: amount.atoms,
+            });
+            process.stdout.write(`✓ Sonar quote works (${quote.quote_id})\n`);
+        }
+        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);
+        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");
+    }
+    catch (error) {
+        if (error instanceof StrataApiError) {
+            throw new Error(friendlyApiError(error.code, error.message));
+        }
+        throw error;
+    }
+}
 async function runStdio(options) {
     const runtime = await createStrataMcpServer(options);
     const transport = new StdioServerTransport();
@@ -161,6 +202,10 @@ function safeError(error) {
 }
 async function main() {
     const options = parse(process.argv.slice(2));
+    if (options.command === "doctor") {
+        await runDoctor(options);
+        return;
+    }
     const sessionAutonomy = await sessionAutonomyFromEnv(process.env);
     const withSession = sessionAutonomy ? { ...options, sessionAutonomy } : options;
     if (sessionAutonomy) {

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

@@ -17,21 +17,21 @@ export declare const STRATA_AGENT_HARNESS: {
         readonly manifest: "https://api.stratabook.app/.well-known/strata-agent.json";
     };
     readonly interfaces: {
-        readonly mcp_tool_order: readonly ["strata_capabilities", "strata_action_graph", "strata_platform_graph", "strata_status", "strata_markets", "strata_marks", "strata_candles", "strata_twaps", "strata_twap_challenge", "strata_twap_cancel", "strata_twap_prepare", "strata_twap_submit", "strata_portfolio", "strata_portfolio_history", "strata_market_making_status", "strata_market_making_reputation", "strata_market_making_prepare", "strata_market_making_submit_and_wait", "strata_vault_status", "strata_vault_setup", "strata_vault_deposit", "strata_vault_withdraw", "strata_vault_delegate", "strata_vault_policy", "strata_vault_pause", "strata_vault_submit", "strata_vault_submission", "strata_rewards", "strata_referrals", "strata_referral_link", "strata_referral_claim", "strata_bugs", "strata_bug_submit", "strata_quote", "strata_exact_output_quote", "strata_swap_quote", "strata_execution_challenge", "strata_execution_prepare", "strata_execution_submit", "strata_execution_status", "strata_order_challenge", "strata_order_prepare", "strata_order_submit", "strata_order_status"];
+        readonly mcp_tool_order: readonly ["strata_capabilities", "strata_action_graph", "strata_platform_graph", "strata_status", "strata_markets", "strata_marks", "strata_candles", "strata_twaps", "strata_twap_challenge", "strata_twap_cancel", "strata_twap_prepare", "strata_twap_submit", "strata_portfolio", "strata_portfolio_history", "strata_market_making_status", "strata_market_making_reputation", "strata_market_making_prepare", "strata_market_making_submit_and_wait", "strata_vault_status", "strata_vault_setup", "strata_vault_deposit", "strata_vault_withdraw", "strata_vault_delegate", "strata_vault_policy", "strata_vault_pause", "strata_vault_submit", "strata_vault_submission", "strata_rewards", "strata_referrals", "strata_referral_link", "strata_referral_claim", "strata_bugs", "strata_bug_submit", "strata_quote", "strata_trade", "strata_exact_output_quote", "strata_swap_quote", "strata_execution_challenge", "strata_execution_prepare", "strata_execution_submit", "strata_execution_status", "strata_order_challenge", "strata_order_prepare", "strata_order_submit", "strata_order_status"];
         readonly terminal: readonly ["npx -y @stratabook/sdk capabilities --json", "npx -y @stratabook/sdk action-graph --json", "npx -y @stratabook/sdk platform-graph --json", "npx -y @stratabook/sdk platform-status --json", "npx -y @stratabook/sdk mark --market-id MARKET_ID --json", "npx -y @stratabook/sdk candles --market-id MARKET_ID --from-ms FROM_MS --to-ms TO_MS --resolution-seconds 300 --json", "npx -y @stratabook/sdk execution-status --market-id MARKET_ID --execution-id EXECUTION_ID --json", "npx -y @stratabook/sdk twaps --market-id MARKET_ID --wallet WALLET_PUBLIC_KEY --json", "npx -y @stratabook/sdk twap-challenge --market-id MARKET_ID --owner-wallet OWNER_PUBLIC_KEY --session-public-key SESSION_PUBLIC_KEY --side buy --total-size-atoms TOTAL_ATOMS --slices 10 --tolerance-bps 100 --interval-slots 100 --limit-price-atoms PRICE_ATOMS --json", "npx -y @stratabook/sdk twap-cancel --market-id MARKET_ID --owner-wallet OWNER_PUBLIC_KEY --session-public-key SESSION_PUBLIC_KEY --twap-id TWAP_ID --json", "npx -y @stratabook/sdk twap-prepare --market-id MARKET_ID --owner-wallet OWNER_PUBLIC_KEY --session-public-key SESSION_PUBLIC_KEY --side buy --total-size-atoms TOTAL_ATOMS --slices 10 --tolerance-bps 100 --interval-slots 100 --limit-price-atoms PRICE_ATOMS --json", "npx -y @stratabook/sdk twap-submit --market-id MARKET_ID --twap-control-id CONTROL_ID --signed-transaction-base64 TRANSACTION --idempotency-key KEY --json", "npx -y @stratabook/sdk account --wallet WALLET_PUBLIC_KEY --json", "npx -y @stratabook/sdk portfolio-history --wallet WALLET_PUBLIC_KEY --range 24h --json", "npx -y @stratabook/sdk maker-status --market-id MARKET_ID --wallet WALLET_PUBLIC_KEY --json", "npx -y @stratabook/sdk maker-reputation --market-id MARKET_ID --wallet WALLET_PUBLIC_KEY --json", "npx -y @stratabook/sdk vault-status --wallet WALLET_PUBLIC_KEY --session-public-key SESSION_PUBLIC_KEY --json", "npx -y @stratabook/sdk session-keygen --json", "npx -y @stratabook/sdk vault-setup --wallet WALLET_PUBLIC_KEY --session-public-key SESSION_PUBLIC_KEY --json", "npx -y @stratabook/sdk vault-deposit --wallet WALLET_PUBLIC_KEY --market-id MARKET_ID --asset-id ASSET_ID --amount-atoms AMOUNT --session-public-key SESSION_PUBLIC_KEY --json", "npx -y @stratabook/sdk vault-withdraw --wallet WALLET_PUBLIC_KEY --market-id MARKET_ID --asset-id ASSET_ID --destination-wallet DESTINATION_WALLET --amount-atoms AMOUNT --json", "npx -y @stratabook/sdk vault-delegate --wallet WALLET_PUBLIC_KEY --session-public-key SESSION_PUBLIC_KEY --action revoke --json", "npx -y @stratabook/sdk vault-policy --wallet WALLET_PUBLIC_KEY --mode restricted --allowed-wallets DESTINATION_WALLET --json", "npx -y @stratabook/sdk vault-pause --wallet WALLET_PUBLIC_KEY --paused true --json", "npx -y @stratabook/sdk rewards --wallet WALLET_PUBLIC_KEY --json", "npx -y @stratabook/sdk referrals --wallet WALLET_PUBLIC_KEY --json", "npx -y @stratabook/sdk referral-link --wallet WALLET_PUBLIC_KEY --code REFERRAL_CODE --json", "npx -y @stratabook/sdk referral-claim --wallet WALLET_PUBLIC_KEY --json", "npx -y @stratabook/sdk bugs --wallet WALLET_PUBLIC_KEY --json", "npx -y @stratabook/sdk bug-payload --message REPORT_TEXT --json", "npx -y @stratabook/sdk markets --json", "npx -y @stratabook/sdk quote --market SOL/USDC --side sell --amount-atoms 10000000 --json", "npx -y @stratabook/sdk swap-quote --input-asset-id INPUT_ASSET_ID --output-asset-id OUTPUT_ASSET_ID --amount-atoms 10000000 --json", "npx -y @stratabook/sdk order-slo --market-id MARKET_ID --owner-wallet OWNER_PUBLIC_KEY --json"];
     };
     readonly workflow: readonly [{
         readonly id: "discover_capabilities";
-        readonly instruction: "Read the live capability catalog before every objective. Never infer permission from documentation, package support, or an earlier session.";
+        readonly instruction: "Call the requested read-only tool directly. Read the live capability catalog only when a requested tool is unavailable, the objective is advanced or ambiguous, or the user explicitly asks what Strata supports. Never turn capability discovery into a prerequisite for a normal market, book, account, or quote request.";
     }, {
         readonly id: "establish_mode";
-        readonly instruction: "Read the compact action graph and the complete platform graph, then identify which operation and workflow nodes are live. The external agent owner configures its permissions and signer authority; static documentation never enables a Strata operation.";
+        readonly instruction: "Use the compact default MCP tools for ordinary requests. Read the action graphs and use the advanced tool surface only for an integration that needs explicit challenge, prepare, sign, and submit control. The external agent owner configures permissions and signer authority.";
     }, {
         readonly id: "understand_objective";
         readonly instruction: "Resolve the user's market or input/output assets, side when applicable, amount, and tolerance. Ask before proceeding when any economically meaningful input is ambiguous.";
     }, {
         readonly id: "discover_market";
-        readonly instruction: "List catalog assets and markets, select currently available product identities, and use discovered decimals. Do not guess identifiers or token decimals.";
+        readonly instruction: "Pass familiar labels such as SOL/USDC to simple tools. Call strata_markets only when the market is unknown or a low-level operation needs opaque IDs and decimals. Do not guess identifiers or token decimals.";
     }, {
         readonly id: "read_market_data";
         readonly instruction: "When books.read is live, use the opaque market ID to read the Strata book, status, fees, and recent trades. Subscribe to the market stream for changes and recover from any sequence gap with a fresh snapshot.";
@@ -73,13 +73,13 @@ export declare const STRATA_AGENT_HARNESS: {
         readonly instruction: "When mm.reputation.read is live, read the maker's record by wallet address (public, no signature). Use the tier, reliability counters, tier-progress gates, signed-quote eligibility, and minimum cadence before choosing the maker transport; do not infer hidden counterparties or execution paths.";
     }, {
         readonly id: "preserve_atoms";
-        readonly instruction: "Represent token amounts as unsigned base-10 atomic strings. Never pass settlement amounts through floating-point arithmetic.";
+        readonly instruction: "For simple MCP tools, prefer exact human strings such as 0.1 SOL, 20 USDC, or $20; the MCP resolves decimals without floating point. For SDK and advanced tools, represent settlement amounts as unsigned base-10 atomic strings and never use floating-point arithmetic.";
     }, {
         readonly id: "authorize_community_actions";
         readonly instruction: "For referral link or claim actions, generate the exact official SDK authorization payload, have the affected owner wallet sign it externally, and submit only the detached signature with the same referral code or payout wallet binding.";
     }, {
         readonly id: "request_quote";
-        readonly instruction: "Request a fresh Sonar quote using either a selected market and explicit side or selected input/output asset IDs, plus exact input atoms and the execution tolerance supplied by the external agent.";
+        readonly instruction: "Call strata_quote directly with a market label, side, and exact human amount. Use opaque asset IDs or exact atoms only for the advanced swap and protocol interfaces. The tolerance is the user's economic choice; zero is the safe default.";
     }, {
         readonly id: "validate_quote";
         readonly instruction: "Verify the quote binds to the selected market and side or the selected input/output assets, plus the exact input and tolerance. Check labelled fees, minimum output, price impact, server time, and expiry.";
@@ -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 Agent Harness 1.0. Start every objective with strata_capabilities, then strata_action_graph, then strata_platform_graph, then strata_status, then strata_markets. Read strata://agent-harness/v1, strata://action-graph/v1, and strata://platform-graph/v2. The external agent owner controls permission and signer authority. Strata accepts public keys, detached signatures, and signed transactions, never private keys or seed phrases. Resolve a market and side or catalog input/output asset IDs, plus exact input atoms and tolerance, before strata_quote or strata_swap_quote. When portfolio.read is live, read the owner's live Vault portfolio before sizing any action and treat null USD totals as an incomplete valuation, never as zero. When mm.status.read is live, reconcile the owner's own maker products, exposure, and dead-man guards through the authorized status read before and after every maker action, and when mm.fills.stream is live keep the official SDK's authenticated maker stream open to apply contiguous maker fills and exposure changes. 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; the token carries no signing authority and survives stateless HTTP requests. When algos.twap.stream is live, follow TWAP progress through the official SDK's sequenced TWAP stream instead of polling, and when execution.stream is live watch prepared execution handles through the sequenced execution stream. Before selecting a maker transport, read the externally authorized owner-scoped maker reputation record and follow its signed-quote eligibility, cadence, and tier-progress fields. Treat amounts as unsigned base-10 token atoms; check quote bindings, labelled fees, minimum output, and expiry. To execute or control a resting order: request a challenge, verify its quote or exact opaque order bindings, sign canonical authorization bytes externally, prepare, verify and sign the returned transaction externally, then submit with idempotency. When websocket order transport is live, prefer the official SDK persistent command stream, choose explicit self-trade prevention, keep its durable dead-man guard armed for resting exposure, and distinguish immediate RPC broadcast from pushed terminal chain status. If submission is ambiguous, recover durable status with the same control ID and idempotency key. Order control supports place, cancel, bounded cancel-all, atomic replace, and atomic heterogeneous batches of up to six operations. Stop on ambiguity, sequence gaps, unavailable capabilities, paused markets, unsupported contracts, 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. 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

@@ -53,6 +53,7 @@ export const STRATA_AGENT_HARNESS = {
             "strata_bugs",
             "strata_bug_submit",
             "strata_quote",
+            "strata_trade",
             "strata_exact_output_quote",
             "strata_swap_quote",
             "strata_execution_challenge",
@@ -104,11 +105,11 @@ export const STRATA_AGENT_HARNESS = {
     "workflow": [
         {
             "id": "discover_capabilities",
-            "instruction": "Read the live capability catalog before every objective. Never infer permission from documentation, package support, or an earlier session."
+            "instruction": "Call the requested read-only tool directly. Read the live capability catalog only when a requested tool is unavailable, the objective is advanced or ambiguous, or the user explicitly asks what Strata supports. Never turn capability discovery into a prerequisite for a normal market, book, account, or quote request."
         },
         {
             "id": "establish_mode",
-            "instruction": "Read the compact action graph and the complete platform graph, then identify which operation and workflow nodes are live. The external agent owner configures its permissions and signer authority; static documentation never enables a Strata operation."
+            "instruction": "Use the compact default MCP tools for ordinary requests. Read the action graphs and use the advanced tool surface only for an integration that needs explicit challenge, prepare, sign, and submit control. The external agent owner configures permissions and signer authority."
         },
         {
             "id": "understand_objective",
@@ -116,7 +117,7 @@ export const STRATA_AGENT_HARNESS = {
         },
         {
             "id": "discover_market",
-            "instruction": "List catalog assets and markets, select currently available product identities, and use discovered decimals. Do not guess identifiers or token decimals."
+            "instruction": "Pass familiar labels such as SOL/USDC to simple tools. Call strata_markets only when the market is unknown or a low-level operation needs opaque IDs and decimals. Do not guess identifiers or token decimals."
         },
         {
             "id": "read_market_data",
@@ -172,7 +173,7 @@ export const STRATA_AGENT_HARNESS = {
         },
         {
             "id": "preserve_atoms",
-            "instruction": "Represent token amounts as unsigned base-10 atomic strings. Never pass settlement amounts through floating-point arithmetic."
+            "instruction": "For simple MCP tools, prefer exact human strings such as 0.1 SOL, 20 USDC, or $20; the MCP resolves decimals without floating point. For SDK and advanced tools, represent settlement amounts as unsigned base-10 atomic strings and never use floating-point arithmetic."
         },
         {
             "id": "authorize_community_actions",
@@ -180,7 +181,7 @@ export const STRATA_AGENT_HARNESS = {
         },
         {
             "id": "request_quote",
-            "instruction": "Request a fresh Sonar quote using either a selected market and explicit side or selected input/output asset IDs, plus exact input atoms and the execution tolerance supplied by the external agent."
+            "instruction": "Call strata_quote directly with a market label, side, and exact human amount. Use opaque asset IDs or exact atoms only for the advanced swap and protocol interfaces. The tolerance is the user's economic choice; zero is the safe default."
         },
         {
             "id": "validate_quote",
@@ -788,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 Agent Harness 1.0. Start every objective with strata_capabilities, then strata_action_graph, then strata_platform_graph, then strata_status, then strata_markets. Read strata://agent-harness/v1, strata://action-graph/v1, and strata://platform-graph/v2. The external agent owner controls permission and signer authority. Strata accepts public keys, detached signatures, and signed transactions, never private keys or seed phrases. Resolve a market and side or catalog input/output asset IDs, plus exact input atoms and tolerance, before strata_quote or strata_swap_quote. When portfolio.read is live, read the owner's live Vault portfolio before sizing any action and treat null USD totals as an incomplete valuation, never as zero. When mm.status.read is live, reconcile the owner's own maker products, exposure, and dead-man guards through the authorized status read before and after every maker action, and when mm.fills.stream is live keep the official SDK's authenticated maker stream open to apply contiguous maker fills and exposure changes. 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; the token carries no signing authority and survives stateless HTTP requests. When algos.twap.stream is live, follow TWAP progress through the official SDK's sequenced TWAP stream instead of polling, and when execution.stream is live watch prepared execution handles through the sequenced execution stream. Before selecting a maker transport, read the externally authorized owner-scoped maker reputation record and follow its signed-quote eligibility, cadence, and tier-progress fields. Treat amounts as unsigned base-10 token atoms; check quote bindings, labelled fees, minimum output, and expiry. To execute or control a resting order: request a challenge, verify its quote or exact opaque order bindings, sign canonical authorization bytes externally, prepare, verify and sign the returned transaction externally, then submit with idempotency. When websocket order transport is live, prefer the official SDK persistent command stream, choose explicit self-trade prevention, keep its durable dead-man guard armed for resting exposure, and distinguish immediate RPC broadcast from pushed terminal chain status. If submission is ambiguous, recover durable status with the same control ID and idempotency key. Order control supports place, cancel, bounded cancel-all, atomic replace, and atomic heterogeneous batches of up to six operations. Stop on ambiguity, sequence gaps, unavailable capabilities, paused markets, unsupported contracts, 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. 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/server.d.ts

@@ -1,11 +1,14 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StrataClient, StrataPlatformClient, type CapabilityCatalog } from "@stratabook/sdk";
 import { type SessionAutonomy } from "./autonomy.js";
+import { type StrataMcpToolMode } from "./usability.js";
 export interface StrataMcpOptions {
     apiBase?: string;
     timeoutMs?: number;
     client?: StrataClient;
     platformClient?: StrataPlatformClient;
+    /** Compact direct-use tools by default; advanced exposes the full protocol surface. */
+    toolMode?: StrataMcpToolMode;
     /**
      * When set, the MCP may finish trades itself with this Vault session key,
      * bounded by the user-owned autonomy slider. Absent = the calm default:

package/dist/src/server.js

@@ -4,6 +4,7 @@ import { decideAutonomy, estimateBaseNotionalUsd, quoteNotionalUsd, MarketMetaRe
 import * as z from "zod/v4";
 import { STRATA_AGENT_HARNESS, STRATA_AGENT_HARNESS_INSTRUCTIONS, STRATA_AGENT_HARNESS_URI, STRATA_ACTION_GRAPH_URI, } from "./generated-harness.js";
 import { SERVER_VERSION } from "./version.js";
+import { SIMPLE_TOOL_NAMES, formatAtoms, friendlyApiError, humanQuoteAmount, } from "./usability.js";
 const REFRESH_INTERVAL_MS = 5_000;
 export const STRATA_PLATFORM_GRAPH_URI = "strata://platform-graph/v2";
 const makerPublicKeySchema = z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/);
@@ -158,6 +159,8 @@ function decodeMakerPreparationToken(token) {
 const LEGACY_TOOL_CAPABILITIES = {
     strata_markets: { ids: ["markets.read"] },
     strata_quote: { ids: ["quotes.read"] },
+    // Always available for a read-only preview; it only submits when a session exists.
+    strata_trade: { ids: ["quotes.read"] },
     strata_exact_output_quote: { ids: ["quotes.read"] },
     strata_execution_challenge: { ids: ["trade.prepare"] },
     strata_execution_prepare: { ids: ["trade.prepare"] },
@@ -181,6 +184,7 @@ const PLATFORM_TOOL_CAPABILITIES = {
     strata_candles: { ids: ["market_data.candles.read"] },
     strata_marks: { ids: ["market_data.marks.read"] },
     strata_quote: { ids: ["quotes.market.read"] },
+    strata_trade: { ids: ["quotes.market.read"] },
     strata_swap_quote: { ids: ["quotes.swap.read"] },
     strata_exact_output_quote: { ids: ["quotes.exact_output.read"] },
     strata_execution_challenge: { ids: ["execution.prepare"] },
@@ -393,6 +397,7 @@ async function platformMarketIdentities(platformClient) {
 }
 export async function createStrataMcpServer(options = {}) {
     const client = strataClient(options);
+    const toolMode = options.toolMode ?? "simple";
     const platformClient = options.platformClient ?? new StrataPlatformClient({
         apiBase: options.apiBase,
         timeoutMs: options.timeoutMs,
@@ -1269,8 +1274,9 @@ export async function createStrataMcpServer(options = {}) {
     }));
     const quote = registerTool("strata_quote", {
         title: "Sonar quote",
-        description: "Request a short-lived Sonar quote for a Strata market. Returns expected "
-            + "output, minimum output, fees, price impact, and expiry.",
+        description: "Request a short-lived Sonar quote. Use a market label and a human amount such as "
+            + "0.1 SOL, 20 USDC, or $20; exact input atoms remain available for advanced clients. "
+            + "Returns expected output, fees, price impact, and expiry.",
         inputSchema: {
             market: z
                 .string()
@@ -1278,11 +1284,18 @@ export async function createStrataMcpServer(options = {}) {
                 .max(128)
                 .describe("Market label such as SOL/USDC, or its public market ID."),
             side: z.enum(["buy", "sell"]).describe("Buy or sell the market's base asset."),
+            amount: z
+                .string()
+                .min(1)
+                .max(64)
+                .optional()
+                .describe("Human input amount, for example 0.1 SOL, 20 USDC, or $20."),
             amountInAtoms: z
                 .string()
                 .regex(/^[0-9]+$/)
                 .max(20)
-                .describe("Exact input amount in the input token's smallest atomic unit."),
+                .optional()
+                .describe("Advanced: exact input amount in the input token's smallest atomic unit."),
             maximumToleranceBps: z
                 .number()
                 .int()
@@ -1300,15 +1313,36 @@ export async function createStrataMcpServer(options = {}) {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ market, side, amountInAtoms, maximumToleranceBps }) => guardedTool(client, "quotes.read", async () => {
+    }, async ({ market, side, amount, amountInAtoms, maximumToleranceBps }) => guardedTool(client, "quotes.read", async () => {
+        if ((amount === undefined) === (amountInAtoms === undefined)) {
+            return toolError("invalid_amount", "Give exactly one amount: a human value such as 0.1 SOL, or amountInAtoms for advanced use.", false);
+        }
+        let resolvedMarket = market;
+        let resolvedAtoms = amountInAtoms;
+        let display;
+        if (amount !== undefined) {
+            try {
+                const parsed = humanQuoteAmount((await client.markets()).markets, market, side, amount);
+                resolvedMarket = parsed.market.label;
+                resolvedAtoms = parsed.atoms;
+                display = {
+                    input: parsed.display,
+                    outputSymbol: parsed.outputSymbol,
+                    outputDecimals: parsed.outputDecimals,
+                };
+            }
+            catch (error) {
+                return toolError("invalid_amount", safeMessage(error), false);
+            }
+        }
         const request = {
-            market,
+            market: resolvedMarket,
             side,
-            amountInAtoms,
+            amountInAtoms: resolvedAtoms,
             maximumToleranceBps,
         };
-        const response = await client.quote(request);
-        return toolResult(response, quoteSummary(response));
+        const response = await retryReadOnce(() => client.quote(request));
+        return toolResult(response, quoteSummary(response, display));
     }));
     const exactOutputQuote = registerTool("strata_exact_output_quote", {
         title: "Sonar exact-output quote",
@@ -1354,9 +1388,90 @@ export async function createStrataMcpServer(options = {}) {
             amountOutAtoms,
             maximumToleranceBps,
         };
-        const response = await client.quote(request);
+        const response = await retryReadOnce(() => client.quote(request));
         return toolResult(response, quoteSummary(response));
     }));
+    registerTool("strata_trade", {
+        title: "Trade on Strata",
+        description: "Quote and trade in one obvious tool. Human amounts such as 0.1 SOL and $20 are supported. "
+            + "Without a trading connection it returns the live read-only quote plus one setup link; "
+            + "with a session it follows the user's autonomy limits and may submit.",
+        inputSchema: {
+            market: z.string().min(1).max(128).describe("Market label, for example SOL/USDC."),
+            side: z.enum(["buy", "sell"]),
+            amount: z.string().min(1).max(64).optional()
+                .describe("Human input amount, for example 0.1 SOL, 20 USDC, or $20."),
+            amountInAtoms: z.string().regex(/^[1-9][0-9]*$/).max(20).optional()
+                .describe("Advanced alternative: exact input token atoms."),
+            maximumToleranceBps: z.number().int().min(0).max(1_000).optional()
+                .default(DEFAULT_MAXIMUM_TOLERANCE_BPS),
+            idempotencyKey: z.string().min(1).max(64).regex(/^[A-Za-z0-9._-]+$/).optional(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ market, side, amount, amountInAtoms, maximumToleranceBps, idempotencyKey }) => guardedTool(client, "quotes.read", async () => {
+        if ((amount === undefined) === (amountInAtoms === undefined)) {
+            return toolError("invalid_amount", "Give exactly one amount: a human value such as 0.1 SOL, or amountInAtoms for advanced use.", false);
+        }
+        const sonarMarkets = (await client.markets()).markets;
+        let resolvedMarket = market;
+        let resolvedAtoms = amountInAtoms;
+        let inputDisplay = amountInAtoms ? `${amountInAtoms} input atoms` : amount;
+        if (amount !== undefined) {
+            try {
+                const parsed = humanQuoteAmount(sonarMarkets, market, side, amount);
+                resolvedMarket = parsed.market.label;
+                resolvedAtoms = parsed.atoms;
+                inputDisplay = parsed.display;
+            }
+            catch (error) {
+                return toolError("invalid_amount", safeMessage(error), false);
+            }
+        }
+        const freshQuote = await retryReadOnce(() => client.quote({
+            market: resolvedMarket,
+            side,
+            amountInAtoms: resolvedAtoms,
+            maximumToleranceBps,
+        }));
+        if (!options.sessionAutonomy) {
+            return toolResult({
+                executed: false,
+                reason: "trading_not_connected",
+                quote: freshQuote,
+                connect_url: "https://stratabook.app/agents",
+            }, `Live quote ready for ${inputDisplay}; no transaction was sent. Trading is not connected. `
+                + "Open https://stratabook.app/agents when you want to trade; read-only tools need no setup.");
+        }
+        const liveCatalog = await client.capabilities();
+        if (!capabilityAvailable(liveCatalog, "trade.submit")) {
+            return toolError("trading_temporarily_unavailable", "The quote works, but trading submission is temporarily unavailable. No transaction was sent.", true);
+        }
+        const sonar = sonarMarkets.find((candidate) => candidate.market_pda === freshQuote.market_id)
+            ?? sonarMarkets.find((candidate) => candidate.label === resolvedMarket);
+        const notional = sonar
+            ? quoteNotionalUsd(freshQuote.side, freshQuote.amount_in_atoms, freshQuote.minimum_output_atoms, sonar.quote_decimals)
+            : null;
+        const resolver = new MarketMetaResolver(platformClient, async () => sonarMarkets, () => Date.now());
+        const marketId = sonar ? await resolver.idForLabel(sonar.label) : null;
+        const decision = decideAutonomy(options.sessionAutonomy, marketId ?? "", notional, Date.now());
+        if (!decision.allow) {
+            return toolResult({ executed: false, reason: decision.reason, quote: freshQuote }, `${decision.reason} The live quote is attached; no transaction was sent.`);
+        }
+        const receipt = await client.executeQuote({
+            quote: freshQuote,
+            ownerWallet: options.sessionAutonomy.ownerWallet,
+            signer: options.sessionAutonomy.signer,
+            ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+        });
+        if (notional !== null)
+            options.sessionAutonomy.dailyBudget.record(notional, Date.now());
+        return toolResult({ executed: true, receipt, notional_usd: notional }, `Executed ${side} ${inputDisplay} as ${receipt.signature}.`);
+    }));
     registerTool("strata_swap_quote", {
         title: "Sonar asset swap quote",
         description: "Request short-lived exact-input customer economics between two opaque Strata asset IDs.",
@@ -1963,7 +2078,7 @@ export async function createStrataMcpServer(options = {}) {
         makerCurrentPrepare,
         makerCurrentSubmit,
     ];
-    applyToolAvailability(registeredTools, initialCatalog, initialPlatformCatalog);
+    applyToolAvailability(registeredTools, initialCatalog, initialPlatformCatalog, toolMode);
     let closed = false;
     const refresh = async () => {
         if (closed)
@@ -1972,7 +2087,7 @@ export async function createStrataMcpServer(options = {}) {
             client.capabilities(),
             platformClient.discovery.read(),
         ]);
-        applyToolAvailability(registeredTools, catalog, platformCatalog);
+        applyToolAvailability(registeredTools, catalog, platformCatalog, toolMode);
     };
     const timer = setInterval(() => {
         refresh().catch((error) => {
@@ -2007,19 +2122,22 @@ function registerAutonomyTools(registerTool, client, platformClient, autonomy, n
         },
     }, async () => {
         const howToChange = {
-            level_env: "STRATA_AUTONOMY = ask | limits | instant",
-            per_trade_env: "STRATA_AUTONOMY_MAX_USD_PER_TRADE",
-            per_day_env: "STRATA_AUTONOMY_MAX_USD_PER_DAY",
-            markets_env: "STRATA_AUTONOMY_MARKETS (comma-separated opaque market IDs)",
-            session_env: "STRATA_SESSION_SECRET_KEY + STRATA_OWNER_WALLET (register the key on the Agents page)",
+            setup: "Open the Agents page, connect the owner wallet, register once, then copy the MCP trading config into your client's local settings.",
             agents_page: "https://stratabook.app/agents",
-            note: "Only the user changes these; an agent can offer but never raise its own level.",
+            generic_clients: "Claude Desktop, Cursor, Windsurf, Codex, or any local stdio MCP host",
+            note: "Read-only tools need none of this. Only the user changes trading authority; an agent can never raise its own level.",
+            advanced_environment_reference: {
+                level_env: "STRATA_AUTONOMY = ask | limits | instant",
+                per_trade_env: "STRATA_AUTONOMY_MAX_USD_PER_TRADE",
+                per_day_env: "STRATA_AUTONOMY_MAX_USD_PER_DAY",
+                markets_env: "STRATA_AUTONOMY_MARKETS (comma-separated opaque market IDs)",
+                session_env: "STRATA_SESSION_SECRET_KEY + STRATA_OWNER_WALLET (register the key on the Agents page)",
+            },
         };
         if (!autonomy) {
-            return toolResult({ session_configured: false, level: "ask", how_to_change: howToChange }, "Autonomy: ask (no session key configured). I can prepare trades for you to sign, "
-                + "but I cannot sign any myself. To let me trade unattended, register a Vault session "
-                + "key on the Agents page and set STRATA_SESSION_SECRET_KEY (+ STRATA_OWNER_WALLET), "
-                + "then choose STRATA_AUTONOMY=limits or instant.");
+            return toolResult({ session_configured: false, level: "ask", how_to_change: howToChange }, "Read-only is ready. Trading is not connected, so I cannot send transactions. "
+                + "If you want trading, open https://stratabook.app/agents and copy its MCP trading config "
+                + "into your client; never paste the session secret into chat.");
         }
         const { config } = autonomy;
         const spentToday = autonomy.dailyBudget.spentToday(nowMs());
@@ -2077,12 +2195,12 @@ function registerAutonomyTools(registerTool, client, platformClient, autonomy, n
             openWorldHint: true,
         },
     }, async (args) => guardedTool(client, "trade.submit", async () => {
-        const quote = await client.quote({
+        const quote = await retryReadOnce(() => client.quote({
             market: args.market,
             side: args.side,
             amountInAtoms: args.amountInAtoms,
             ...(args.toleranceBps === undefined ? {} : { toleranceBps: args.toleranceBps }),
-        });
+        }));
         const sonar = (await client.markets()).markets.find((market) => market.market_pda === quote.market_id);
         const notional = sonar
             ? quoteNotionalUsd(quote.side, quote.amount_in_atoms, quote.minimum_output_atoms, sonar.quote_decimals)
@@ -2261,11 +2379,12 @@ function requirementAvailable(requirement, available) {
         ? requirement.ids.some(available)
         : requirement.ids.every(available);
 }
-function applyToolAvailability(handles, catalog, platformCatalog) {
+function applyToolAvailability(handles, catalog, platformCatalog, toolMode) {
     for (const [name, tool] of handles) {
         const legacyAvailable = requirementAvailable(LEGACY_TOOL_CAPABILITIES[name], (id) => capabilityAvailable(catalog, id));
         const platformAvailable = requirementAvailable(PLATFORM_TOOL_CAPABILITIES[name], (id) => platformCapabilityAvailable(platformCatalog, id));
-        setToolEnabled(tool, legacyAvailable && platformAvailable);
+        const modeAvailable = toolMode === "advanced" || SIMPLE_TOOL_NAMES.has(name);
+        setToolEnabled(tool, modeAvailable && legacyAvailable && platformAvailable);
     }
 }
 function setToolEnabled(tool, enabled) {
@@ -2284,7 +2403,7 @@ async function guardedTool(client, capabilityId, operation) {
     }
     catch (error) {
         if (error instanceof StrataApiError) {
-            return toolError(error.code, error.message, error.retryable);
+            return toolError(error.code, friendlyApiError(error.code, error.message), error.retryable);
         }
         return toolError("request_failed", safeMessage(error), true);
     }
@@ -2295,16 +2414,35 @@ async function safeTool(operation) {
     }
     catch (error) {
         if (error instanceof StrataApiError) {
-            return toolError(error.code, error.message, error.retryable);
+            return toolError(error.code, friendlyApiError(error.code, error.message), error.retryable);
         }
         return toolError("request_failed", safeMessage(error), true);
     }
 }
+/** Retry an idempotent public read once; trading writes are deliberately never retried here. */
+async function retryReadOnce(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (!(error instanceof StrataApiError) || !error.retryable)
+            throw error;
+        await new Promise((resolve) => setTimeout(resolve, 150));
+        return operation();
+    }
+}
 /**
  * One line that keeps the two numbers apart: price impact is measured from the
  * book; the tolerance is the caller's own floor.
  */
-function quoteSummary(response) {
+function quoteSummary(response, display) {
+    if (display) {
+        const output = `${formatAtoms(response.amount_out_atoms, display.outputDecimals)} ${display.outputSymbol}`;
+        const minimum = `${formatAtoms(response.minimum_output_atoms, display.outputDecimals)} ${display.outputSymbol}`;
+        return (`Sonar ${response.side} quote: ${display.input} → about ${output}; minimum ${minimum}; `
+            + `price impact ${response.price_impact_pct}%; tolerance ${response.maximum_tolerance_bps} bps. `
+            + `This is a read-only quote and expires at ${response.expires_at_ms}.`);
+    }
     return (`Sonar ${response.side} quote: ${response.amount_in_consumed_atoms} input atoms for `
         + `${response.amount_out_atoms} user-net output atoms; price impact ${response.price_impact_pct}% `
         + `(measured from the book); your tolerance ${response.maximum_tolerance_bps} bps, so the `

package/dist/src/usability.d.ts

@@ -0,0 +1,27 @@
+import type { Market } from "@stratabook/sdk";
+export type StrataMcpToolMode = "simple" | "advanced";
+/**
+ * The default surface is intentionally small enough for an agent to choose a
+ * useful tool directly. `advanced` keeps the complete protocol machinery for
+ * integrators that need explicit challenge / prepare / submit control.
+ */
+export declare const SIMPLE_TOOL_NAMES: Set<string>;
+export declare function parseToolMode(raw: string | undefined): StrataMcpToolMode;
+export interface HumanQuoteAmount {
+    readonly atoms: string;
+    readonly market: Market;
+    readonly inputSymbol: string;
+    readonly inputDecimals: number;
+    readonly outputSymbol: string;
+    readonly outputDecimals: number;
+    readonly display: string;
+}
+/** Resolve friendly market spellings without making opaque IDs stop working. */
+export declare function resolveMarket(markets: readonly Market[], requested: string): Market;
+/**
+ * Convert an exact decimal amount to atoms without ever passing through a
+ * floating-point number. For buys the input is quote; for sells it is base.
+ */
+export declare function humanQuoteAmount(markets: readonly Market[], requestedMarket: string, side: "buy" | "sell", amount: string): HumanQuoteAmount;
+export declare function formatAtoms(atoms: string, decimals: number): string;
+export declare function friendlyApiError(code: string, message: string): string;

package/dist/src/usability.js

@@ -0,0 +1,116 @@
+/**
+ * The default surface is intentionally small enough for an agent to choose a
+ * useful tool directly. `advanced` keeps the complete protocol machinery for
+ * integrators that need explicit challenge / prepare / submit control.
+ */
+export const SIMPLE_TOOL_NAMES = new Set([
+    "strata_markets",
+    "strata_quote",
+    "strata_book",
+    "strata_trades",
+    "strata_candles",
+    "strata_marks",
+    "strata_portfolio",
+    "strata_market_making_status",
+    "strata_market_making_prepare",
+    "strata_market_making_submit_and_wait",
+    "strata_autonomy",
+    "strata_trade",
+]);
+export function parseToolMode(raw) {
+    const value = raw?.trim().toLowerCase() || "simple";
+    if (value === "simple" || value === "advanced")
+        return value;
+    throw new TypeError("mode must be simple or advanced");
+}
+/** Resolve friendly market spellings without making opaque IDs stop working. */
+export function resolveMarket(markets, requested) {
+    const trimmed = requested.trim();
+    const normalized = normalizedMarketLabel(trimmed);
+    const match = markets.find((market) => market.market_pda === trimmed || normalizedMarketLabel(market.label) === normalized);
+    if (match)
+        return match;
+    throw new TypeError(`Unknown market ${trimmed}. Try a label from strata_markets, for example SOL/USDC.`);
+}
+/**
+ * Convert an exact decimal amount to atoms without ever passing through a
+ * floating-point number. For buys the input is quote; for sells it is base.
+ */
+export function humanQuoteAmount(markets, requestedMarket, side, amount) {
+    const market = resolveMarket(markets, requestedMarket);
+    // Sonar's base/quote fields may be mint addresses; the public label carries
+    // the display symbols agents and users actually type.
+    const [labelBase, labelQuote] = market.label.split("/", 2).map((part) => part.trim());
+    const inputSymbol = side === "buy"
+        ? labelQuote || market.quote
+        : labelBase || market.base;
+    const inputDecimals = side === "buy" ? market.quote_decimals : market.base_decimals;
+    const outputSymbol = side === "buy"
+        ? labelBase || market.base
+        : labelQuote || market.quote;
+    const outputDecimals = side === "buy" ? market.base_decimals : market.quote_decimals;
+    const value = amount.trim();
+    const dollar = value.startsWith("$");
+    const match = /^(?:\$\s*)?([0-9]+)(?:\.([0-9]+))?(?:\s*([A-Za-z0-9._-]+))?$/.exec(value);
+    if (!match) {
+        throw new TypeError(`amount must look like 0.1 ${inputSymbol} or 20 ${inputSymbol}`);
+    }
+    if (dollar && !isDollarSymbol(inputSymbol)) {
+        throw new TypeError(`$ amounts are only valid when the input token is USD-like; this input is ${inputSymbol}`);
+    }
+    const suppliedSymbol = match[3];
+    if (suppliedSymbol && suppliedSymbol.toLowerCase() !== inputSymbol.toLowerCase()) {
+        throw new TypeError(`This ${side} uses ${inputSymbol} as input, not ${suppliedSymbol}`);
+    }
+    const fraction = match[2] ?? "";
+    if (fraction.length > inputDecimals) {
+        throw new TypeError(`${inputSymbol} supports at most ${inputDecimals} decimal places`);
+    }
+    const scale = 10n ** BigInt(inputDecimals);
+    const atoms = BigInt(match[1]) * scale
+        + BigInt((fraction + "0".repeat(inputDecimals)).slice(0, inputDecimals) || "0");
+    if (atoms <= 0n || atoms > 18446744073709551615n) {
+        throw new TypeError("amount is outside the supported token range");
+    }
+    return {
+        atoms: atoms.toString(),
+        market,
+        inputSymbol,
+        inputDecimals,
+        outputSymbol,
+        outputDecimals,
+        display: `${formatAtoms(atoms.toString(), inputDecimals)} ${inputSymbol}`,
+    };
+}
+export function formatAtoms(atoms, decimals) {
+    if (!/^(?:0|[1-9][0-9]*)$/.test(atoms))
+        return atoms;
+    if (decimals === 0)
+        return atoms;
+    const padded = atoms.padStart(decimals + 1, "0");
+    const whole = padded.slice(0, -decimals);
+    const fraction = padded.slice(-decimals).replace(/0+$/, "");
+    return fraction ? `${whole}.${fraction}` : whole;
+}
+export function friendlyApiError(code, message) {
+    const normalized = code.toLowerCase();
+    if (normalized.includes("session") || normalized.includes("delegate")) {
+        return "Trading is not connected. Open https://stratabook.app/agents, connect your wallet, and copy the MCP trading config for your client. Read-only tools still work now.";
+    }
+    if (normalized.includes("balance") || normalized.includes("fund")) {
+        return "There is not enough available balance for this action. Deposit funds or reduce the amount, then try again.";
+    }
+    if (normalized.includes("warm") || normalized.includes("temporar") || normalized.includes("unavailable")) {
+        return "This market is temporarily warming up. Try again shortly; no transaction was sent.";
+    }
+    if (normalized.includes("expired")) {
+        return "The quote or prepared transaction expired. Request a fresh one and try again.";
+    }
+    return message;
+}
+function normalizedMarketLabel(value) {
+    return value.trim().toUpperCase().replace(/[\s:_-]+/g, "/");
+}
+function isDollarSymbol(symbol) {
+    return ["USD", "USDC", "USDT", "USDG"].includes(symbol.toUpperCase());
+}

package/package.json

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