@stratabook/mcp 0.1.1 → 0.1.3

package/dist/src/cli.js

@@ -3,7 +3,9 @@ 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 { createStrataMcpServer } from "./server.js";
+import { STRATA_AGENT_HARNESS } from "./generated-harness.js";
+import { createStrataMcpServer, probeStrataMcpReadiness } from "./server.js";
+import { SERVER_VERSION } from "./version.js";
 function parse(argv) {
     const values = new Map();
     for (let index = 0; index < argv.length; index++) {
@@ -26,7 +28,7 @@ function parse(argv) {
     }
     const timeoutMs = boundedInteger(values.get("timeout-ms") ?? process.env.STRATA_MCP_TIMEOUT_MS ?? "10000", "timeout-ms", 250, 60_000);
     const port = boundedInteger(values.get("port") ?? process.env.STRATA_MCP_PORT ?? "8787", "port", 1, 65_535);
-    const host = values.get("host") ?? process.env.STRATA_MCP_HOST ?? "127.0.0.1";
+    const host = values.get("host") ?? process.env.STRATA_MCP_HOST ?? "localhost";
     if (!/^[a-zA-Z0-9.:[\]-]+$/.test(host))
         throw new Error("host is invalid");
     return {
@@ -49,13 +51,13 @@ function help() {
 
 Usage:
   strata-mcp
-  strata-mcp --transport http [--host 127.0.0.1] [--port 8787]
+  strata-mcp --transport http [--host localhost] [--port 8787]
 
 Options:
   --transport stdio|http   Local stdio by default; Streamable HTTP for hosting
   --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: 127.0.0.1)
+  --host HOST              HTTP bind host (default: localhost)
   --port N                 HTTP port (default: 8787)
 
 This server is read-only. It accepts no wallet, private key, or session key.
@@ -77,11 +79,26 @@ async function runHttp(options) {
     // local MCP installations from DNS-rebinding attacks.
     const app = createMcpExpressApp({ host: options.host });
     app.disable("x-powered-by");
-    app.get("/health", (_request, response) => {
+    app.get("/health", async (_request, response) => {
+        try {
+            const readiness = await probeStrataMcpReadiness(options);
+            response.status(200).set("Cache-Control", "no-store").json(readiness);
+        }
+        catch (error) {
+            process.stderr.write(`[strata-mcp] readiness failed: ${safeError(error)}\n`);
+            response.status(503).set("Cache-Control", "no-store").json({
+                ok: false,
+                service: "strata-mcp",
+                version: SERVER_VERSION,
+                readiness: "failed",
+            });
+        }
+    });
+    app.get("/.well-known/strata-agent.json", (_request, response) => {
         response
             .status(200)
-            .set("Cache-Control", "no-store")
-            .json({ ok: true, service: "strata-mcp", version: "0.1.0" });
+            .set("Cache-Control", "public, max-age=300")
+            .json(STRATA_AGENT_HARNESS);
     });
     app.post("/mcp", async (request, response) => {
         let runtime;
@@ -99,7 +116,8 @@ async function runHttp(options) {
             await runtime.server.connect(transport);
             await transport.handleRequest(request, response, request.body);
         }
-        catch {
+        catch (error) {
+            process.stderr.write(`[strata-mcp] request failed: ${safeError(error)}\n`);
             if (!response.headersSent) {
                 response.status(500).json({
                     jsonrpc: "2.0",
@@ -127,6 +145,11 @@ async function runHttp(options) {
     process.once("SIGINT", close);
     process.once("SIGTERM", close);
 }
+function safeError(error) {
+    if (!(error instanceof Error))
+        return "unknown_error";
+    return `${error.name}: ${error.message}`.replace(/[\r\n\t]/g, " ").slice(0, 300);
+}
 async function main() {
     const options = parse(process.argv.slice(2));
     if (options.transport === "stdio")

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

@@ -0,0 +1,53 @@
+export declare const STRATA_AGENT_HARNESS: {
+    readonly schema_version: 1;
+    readonly harness_version: "1.0";
+    readonly contract_version: "1.1";
+    readonly name: "Strata Agent Harness";
+    readonly summary: "A capability-gated workflow for agents that explore Strata markets and request validated Sonar quotes.";
+    readonly entrypoints: {
+        readonly documentation: "https://stratabook.org/docs/agent-harness/";
+        readonly capabilities: "https://api.stratabook.app/sonar/capabilities";
+        readonly markets: "https://api.stratabook.app/sonar/markets";
+        readonly mcp: "https://api.stratabook.app/mcp";
+        readonly manifest: "https://api.stratabook.app/.well-known/strata-agent.json";
+    };
+    readonly interfaces: {
+        readonly mcp_tool_order: readonly ["strata_capabilities", "strata_markets", "strata_quote"];
+        readonly terminal: readonly ["npx -y @stratabook/sdk capabilities --json", "npx -y @stratabook/sdk markets --json", "npx -y @stratabook/sdk quote --market SOL/USDC --side sell --amount-atoms 10000000 --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 id: "establish_mode";
+        readonly instruction: "State whether the available session is read-only or exposes a separately authorized prepare or submit capability. Read access never implies permission to move funds.";
+    }, {
+        readonly id: "understand_objective";
+        readonly instruction: "Resolve the user's market, side, amount, and tolerance. Ask before proceeding when any economically meaningful input is ambiguous.";
+    }, {
+        readonly id: "discover_market";
+        readonly instruction: "List markets, select one marked ready, and use its discovered base and quote decimals. Do not guess market identifiers or token decimals.";
+    }, {
+        readonly id: "preserve_atoms";
+        readonly instruction: "Represent token amounts as unsigned base-10 atomic strings. Never pass settlement amounts through floating-point arithmetic.";
+    }, {
+        readonly id: "request_quote";
+        readonly instruction: "Request a fresh Sonar quote with an explicit side, exact input atoms, and user-approved execution tolerance.";
+    }, {
+        readonly id: "validate_quote";
+        readonly instruction: "Verify the quote binds to the selected market, side, and input. Check labelled fees, minimum output, price impact, server time, and expiry.";
+    }, {
+        readonly id: "report_result";
+        readonly instruction: "Report consumed input, expected output, minimum output, fees by asset side, price impact, and remaining validity without inventing private route composition.";
+    }, {
+        readonly id: "authorize_writes";
+        readonly instruction: "If write capabilities are ever exposed, keep prepare and submit separate, require the configured approval, verify immutable economics, and use idempotency.";
+    }, {
+        readonly id: "monitor_outcome";
+        readonly instruction: "After an authorized submission, report the durable receipt or explicit failure. Never claim completion from preparation, signing, or an unconfirmed request.";
+    }];
+    readonly stop_conditions: readonly ["The required live capability is disabled or absent.", "The market is paused, unavailable, or has no reviewed operation path.", "Market, side, amount, decimals, tolerance, or approval is ambiguous.", "The contract version is unsupported or a response contains unknown fields.", "A quote is expired or its market, side, amount, fee, minimum-output, or time binding is inconsistent.", "A requested operation exceeds the exposed tool, account, or policy scope.", "A user asks the agent to receive or expose wallet secrets, private keys, seed phrases, session keys, or production credentials."];
+    readonly safety_rules: readonly ["Never request or accept wallet secrets, private keys, seed phrases, session keys, or production credentials in a prompt.", "Never call undocumented endpoints or reconstruct private Sonar behavior.", "Never silently widen slippage, refresh changed economics, substitute a market, or retry a non-retryable failure.", "Treat capability removal, revocation, expiry, and emergency disable as immediate stop signals.", "The current MCP and terminal tools are read-only unless the live catalog and callable tool list explicitly prove otherwise."];
+};
+export declare const STRATA_AGENT_HARNESS_URI = "strata://agent-harness/v1";
+export declare const STRATA_AGENT_HARNESS_INSTRUCTIONS = "Strata Agent Harness 1.0. Start every objective with strata_capabilities, then strata_markets. Read strata://agent-harness/v1 for the complete workflow. Resolve the market, side, exact input atoms, and tolerance before strata_quote. Treat amounts as unsigned base-10 token atoms; check quote bindings, labelled fees, minimum output, and expiry. Stop on ambiguity, unavailable capabilities, paused markets, unsupported contracts, inconsistent bindings, expiry, or missing approval. Never request wallet secrets, private keys, seed phrases, session keys, or production credentials. Current MCP tools are read-only unless the live catalog and callable tool list explicitly prove otherwise.";

package/dist/src/generated-harness.js

@@ -0,0 +1,87 @@
+// @generated by scripts/generate-agent-entry.mjs. Do not edit manually.
+export const STRATA_AGENT_HARNESS = {
+    "schema_version": 1,
+    "harness_version": "1.0",
+    "contract_version": "1.1",
+    "name": "Strata Agent Harness",
+    "summary": "A capability-gated workflow for agents that explore Strata markets and request validated Sonar quotes.",
+    "entrypoints": {
+        "documentation": "https://stratabook.org/docs/agent-harness/",
+        "capabilities": "https://api.stratabook.app/sonar/capabilities",
+        "markets": "https://api.stratabook.app/sonar/markets",
+        "mcp": "https://api.stratabook.app/mcp",
+        "manifest": "https://api.stratabook.app/.well-known/strata-agent.json"
+    },
+    "interfaces": {
+        "mcp_tool_order": [
+            "strata_capabilities",
+            "strata_markets",
+            "strata_quote"
+        ],
+        "terminal": [
+            "npx -y @stratabook/sdk capabilities --json",
+            "npx -y @stratabook/sdk markets --json",
+            "npx -y @stratabook/sdk quote --market SOL/USDC --side sell --amount-atoms 10000000 --json"
+        ]
+    },
+    "workflow": [
+        {
+            "id": "discover_capabilities",
+            "instruction": "Read the live capability catalog before every objective. Never infer permission from documentation, package support, or an earlier session."
+        },
+        {
+            "id": "establish_mode",
+            "instruction": "State whether the available session is read-only or exposes a separately authorized prepare or submit capability. Read access never implies permission to move funds."
+        },
+        {
+            "id": "understand_objective",
+            "instruction": "Resolve the user's market, side, amount, and tolerance. Ask before proceeding when any economically meaningful input is ambiguous."
+        },
+        {
+            "id": "discover_market",
+            "instruction": "List markets, select one marked ready, and use its discovered base and quote decimals. Do not guess market identifiers or token decimals."
+        },
+        {
+            "id": "preserve_atoms",
+            "instruction": "Represent token amounts as unsigned base-10 atomic strings. Never pass settlement amounts through floating-point arithmetic."
+        },
+        {
+            "id": "request_quote",
+            "instruction": "Request a fresh Sonar quote with an explicit side, exact input atoms, and user-approved execution tolerance."
+        },
+        {
+            "id": "validate_quote",
+            "instruction": "Verify the quote binds to the selected market, side, and input. Check labelled fees, minimum output, price impact, server time, and expiry."
+        },
+        {
+            "id": "report_result",
+            "instruction": "Report consumed input, expected output, minimum output, fees by asset side, price impact, and remaining validity without inventing private route composition."
+        },
+        {
+            "id": "authorize_writes",
+            "instruction": "If write capabilities are ever exposed, keep prepare and submit separate, require the configured approval, verify immutable economics, and use idempotency."
+        },
+        {
+            "id": "monitor_outcome",
+            "instruction": "After an authorized submission, report the durable receipt or explicit failure. Never claim completion from preparation, signing, or an unconfirmed request."
+        }
+    ],
+    "stop_conditions": [
+        "The required live capability is disabled or absent.",
+        "The market is paused, unavailable, or has no reviewed operation path.",
+        "Market, side, amount, decimals, tolerance, or approval is ambiguous.",
+        "The contract version is unsupported or a response contains unknown fields.",
+        "A quote is expired or its market, side, amount, fee, minimum-output, or time binding is inconsistent.",
+        "A requested operation exceeds the exposed tool, account, or policy scope.",
+        "A user asks the agent to receive or expose wallet secrets, private keys, seed phrases, session keys, or production credentials."
+    ],
+    "safety_rules": [
+        "Never request or accept wallet secrets, private keys, seed phrases, session keys, or production credentials in a prompt.",
+        "Never call undocumented endpoints or reconstruct private Sonar behavior.",
+        "Never silently widen slippage, refresh changed economics, substitute a market, or retry a non-retryable failure.",
+        "Treat capability removal, revocation, expiry, and emergency disable as immediate stop signals.",
+        "The current MCP and terminal tools are read-only unless the live catalog and callable tool list explicitly prove otherwise."
+    ]
+};
+export const STRATA_AGENT_HARNESS_URI = "strata://agent-harness/v1";
+export const STRATA_AGENT_HARNESS_INSTRUCTIONS = "Strata Agent Harness 1.0. Start every objective with strata_capabilities, then strata_markets. Read strata://agent-harness/v1 for the complete workflow. Resolve the market, side, exact input atoms, and tolerance before strata_quote. Treat amounts as unsigned base-10 token atoms; check quote bindings, labelled fees, minimum output, and expiry. Stop on ambiguity, unavailable capabilities, paused markets, unsupported contracts, inconsistent bindings, expiry, or missing approval. Never request wallet secrets, private keys, seed phrases, session keys, or production credentials. Current MCP tools are read-only unless the live catalog and callable tool list explicitly prove otherwise.";

package/dist/src/index.d.ts

@@ -1 +1,2 @@
-export { capabilityAvailable, createStrataMcpServer, type StrataMcpOptions, type StrataMcpRuntime, } from "./server.js";
+export { capabilityAvailable, createStrataMcpServer, probeStrataMcpReadiness, type StrataMcpOptions, type StrataMcpReadiness, type StrataMcpRuntime, } from "./server.js";
+export { STRATA_AGENT_HARNESS, STRATA_AGENT_HARNESS_INSTRUCTIONS, STRATA_AGENT_HARNESS_URI, } from "./generated-harness.js";

package/dist/src/index.js

@@ -1 +1,2 @@
-export { capabilityAvailable, createStrataMcpServer, } from "./server.js";
+export { capabilityAvailable, createStrataMcpServer, probeStrataMcpReadiness, } from "./server.js";
+export { STRATA_AGENT_HARNESS, STRATA_AGENT_HARNESS_INSTRUCTIONS, STRATA_AGENT_HARNESS_URI, } from "./generated-harness.js";

package/dist/src/server.d.ts

@@ -10,5 +10,13 @@ export interface StrataMcpRuntime {
     refreshCapabilities(): Promise<void>;
     close(): Promise<void>;
 }
+export interface StrataMcpReadiness {
+    ok: true;
+    service: "strata-mcp";
+    version: string;
+    contract_version: string;
+    harness_version: string;
+}
 export declare function capabilityAvailable(catalog: CapabilityCatalog, id: string): boolean;
+export declare function probeStrataMcpReadiness(options?: StrataMcpOptions): Promise<StrataMcpReadiness>;
 export declare function createStrataMcpServer(options?: StrataMcpOptions): Promise<StrataMcpRuntime>;

package/dist/src/server.js

@@ -1,7 +1,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { DEFAULT_SLIPPAGE_BPS, StrataApiError, StrataClient, } from "@stratabook/sdk";
 import * as z from "zod/v4";
-const SERVER_VERSION = "0.1.1";
+import { STRATA_AGENT_HARNESS, STRATA_AGENT_HARNESS_INSTRUCTIONS, STRATA_AGENT_HARNESS_URI, } from "./generated-harness.js";
+import { SERVER_VERSION } from "./version.js";
 const REFRESH_INTERVAL_MS = 5_000;
 export function capabilityAvailable(catalog, id) {
     return catalog.capabilities.some((capability) => capability.id === id
@@ -10,20 +11,73 @@ export function capabilityAvailable(catalog, id) {
         && capability.risk === "read"
         && capability.mcp_exposure === "read");
 }
-export async function createStrataMcpServer(options = {}) {
-    const client = options.client
+function strataClient(options) {
+    return options.client
         ?? new StrataClient({
             apiBase: options.apiBase,
             timeoutMs: options.timeoutMs,
         });
+}
+export async function probeStrataMcpReadiness(options = {}) {
+    const catalog = await strataClient(options).capabilities();
+    if (catalog.contract_version !== STRATA_AGENT_HARNESS.contract_version) {
+        throw new Error("agent harness and live contract versions differ");
+    }
+    return {
+        ok: true,
+        service: "strata-mcp",
+        version: SERVER_VERSION,
+        contract_version: catalog.contract_version,
+        harness_version: STRATA_AGENT_HARNESS.harness_version,
+    };
+}
+export async function createStrataMcpServer(options = {}) {
+    const client = strataClient(options);
     const initialCatalog = await client.capabilities();
+    if (initialCatalog.contract_version !== STRATA_AGENT_HARNESS.contract_version) {
+        throw new Error("agent harness and live contract versions differ");
+    }
     const server = new McpServer({
         name: "strata",
         version: SERVER_VERSION,
     }, {
-        instructions: "Use Strata to discover available markets and request short-lived Sonar quotes. "
-            + "Token values use exact atomic decimal strings. Check quote expiry and minimum output.",
+        instructions: STRATA_AGENT_HARNESS_INSTRUCTIONS,
     });
+    server.registerResource("strata_agent_harness", STRATA_AGENT_HARNESS_URI, {
+        title: "Strata Agent Harness",
+        description: "Canonical capability-gated first-run workflow for Strata agents.",
+        mimeType: "application/json",
+    }, async () => ({
+        contents: [
+            {
+                uri: STRATA_AGENT_HARNESS_URI,
+                mimeType: "application/json",
+                text: JSON.stringify(STRATA_AGENT_HARNESS),
+            },
+        ],
+    }));
+    server.registerPrompt("strata_start", {
+        title: "Start a Strata objective",
+        description: "Apply the Strata Agent Harness to a concrete read-only objective.",
+        argsSchema: {
+            objective: z
+                .string()
+                .min(1)
+                .max(2_000)
+                .describe("The user's concrete Strata market or quote objective."),
+        },
+    }, async ({ objective }) => ({
+        description: "Capability-gated Strata objective",
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `${STRATA_AGENT_HARNESS_INSTRUCTIONS}\n\nObjective: ${objective.trim()}`,
+                },
+            },
+        ],
+    }));
     server.registerTool("strata_capabilities", {
         title: "Strata capabilities",
         description: "See which Strata features are currently available to MCP clients.",

package/dist/src/version.d.ts

@@ -0,0 +1 @@
+export declare const SERVER_VERSION: string;

package/dist/src/version.js

@@ -0,0 +1,4 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const packageMetadata = require("../../package.json");
+export const SERVER_VERSION = packageMetadata.version;

package/package.json

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