@zktx.io/sui-mcp 0.5.0

package/dist/core/session/workflowState.js

@@ -0,0 +1,80 @@
+import { walletConnectionSelection } from "./walletConnection.js";
+import { isInitialChainObservation } from "./transactionRequest.js";
+export const workflowActions = ["connect", "disconnect", "use_account", "stop_connection", "prepare_review",
+    "request_signature", "cancel", "stop_waiting", "read_result"];
+// Read context may change; an existing review's account binding may not.
+// Both evaluated choices and admission consume this relation with current facts.
+export function reviewPreparationAccount(boundAccount, activeAccount, selectedAccount = activeAccount) {
+    if (!activeAccount)
+        return { allowed: false, message: "No account from a connected wallet is selected for this review." };
+    if (boundAccount && boundAccount !== activeAccount)
+        return { allowed: false,
+            message: `This review uses ${boundAccount}, but the currently selected account is ${activeAccount}.` };
+    if (selectedAccount !== activeAccount)
+        return { allowed: false,
+            message: "The selected account has changed since this request was made." };
+    return { allowed: true, account: activeAccount };
+}
+// Shared domain eligibility. The DB supplies current facts at its decision
+// boundary. Returned choices are advisory; admission still binds concrete input.
+export function workflowEligibility(facts) {
+    const { record, session, request, authority, walletAvailability } = facts;
+    const at = Date.parse(facts.evaluatedAt);
+    const cardRemaining = record?.ownerId === facts.ownerId ? Math.max(0, Date.parse(record.state.expiresAt) - at) : 0;
+    // A later-created input card cannot extend its review session. Admitted
+    // requests and management cards retain their separate observation authority.
+    const remaining = record?.scope === "review" && session && !request
+        ? Math.min(cardRemaining, Math.max(0, Date.parse(session.expiresAt) - at)) : cardRemaining;
+    const inputAvailable = remaining > 0 && record?.state.state === "ready" && record.acceptedInput === undefined;
+    const allowedActions = [];
+    const selection = walletConnectionSelection(facts.connections, at, facts.activeAccount
+        ? { address: facts.activeAccount, walletId: facts.activeAccountConnectionId } : undefined);
+    const usableConnectionId = walletAvailability.status === "available" && facts.walletDependent !== false
+        ? selection.connection?.connectionId : undefined;
+    const assetReadAccount = facts.walletDependent === false ? undefined
+        : usableConnectionId ? selection.assetReadAccount : { status: "address_required" };
+    let preparationIssue;
+    if (record?.scope === "connect") {
+        if (inputAvailable) {
+            allowedActions.push("cancel");
+            if (walletAvailability.status === "available") {
+                if (["connect", "manage"].includes(String(record.state.input.intent)) && selection.pairingAllowed)
+                    allowedActions.push("connect");
+                if (facts.connections.some((item) => item.status === "connected" && !item.pendingAction))
+                    allowedActions.push("disconnect");
+                if (selection.connection)
+                    allowedActions.push("use_account");
+            }
+        }
+        if (remaining > 0 && facts.connection?.status === "awaiting_approval")
+            allowedActions.push("stop_connection");
+    }
+    if (session && inputAvailable && record?.scope === "review" && session.status !== "expired" && Date.parse(session.expiresAt) > at && !session.preparationId) {
+        allowedActions.push("cancel");
+        if (walletAvailability.status === "available" && selection.connection && !session.plans[0]?.reviewModel) {
+            const account = reviewPreparationAccount(session.account, assetReadAccount?.status === "available" ? assetReadAccount.account : undefined);
+            if (!account.allowed)
+                preparationIssue = account.message;
+            else if (!facts.busyForAccount)
+                allowedActions.push("prepare_review");
+            if (!facts.busyForAccount && session.status === "ready_for_wallet_review" && session.reviewState?.transactionReviewData &&
+                (!request || request.reviewRevision !== session.reviewRevision))
+                allowedActions.push("request_signature");
+        }
+    }
+    if (record && session && remaining > 0 && request && request.reviewSessionId === session.id &&
+        authority?.owner_id === facts.ownerId &&
+        (record.operationId === request.attemptId || record.scope === "review_manage" && record.state.input.attemptId === request.attemptId)) {
+        if (["awaiting_signature", "submitting", "awaiting_chain_result"].includes(request.requestStatus))
+            allowedActions.push("stop_waiting");
+        if (isInitialChainObservation(request.requestStatus) || request.requestStatus === "outcome_unknown")
+            allowedActions.push("read_result");
+    }
+    const expiry = session && inputAvailable && record?.scope === "review" && !session.preparationId &&
+        session.status === "ready_for_wallet_review" && (!request || request.reviewRevision !== session.reviewRevision)
+        ? session.reviewState?.humanReadableReview?.freshness.expiresAt : undefined;
+    const nextRead = expiry && session ? Math.min(remaining, Date.parse(session.expiresAt) - at, Date.parse(expiry) - at) : undefined;
+    return { allowedActions, preparationIssue, usableConnectionId, assetReadAccount, connectionConflict: selection.conflict,
+        actionRemainingMs: remaining, inputRemainingMs: inputAvailable ? remaining : 0,
+        ...(nextRead !== undefined && nextRead > 0 ? { nextStateReadAfterMs: nextRead } : {}) };
+}

package/dist/core/session/workflowView.js

@@ -0,0 +1,150 @@
+import { workflowActions } from "./workflowState.js";
+import { z } from "zod";
+import { suiAddressStringSchema, parseSuiAddress } from "../suiAddress.js";
+import { actionPlanSchema, internalSessionStatusSchema, reviewStateOutputSchema } from "../action/schemas.js";
+import { walletConnectionSchema, walletAvailabilitySchema, workflowProgressSchema, WALLET_CONNECTION_POLL_SECONDS, connectionConflictSchema, assetReadAccountSchema } from "./walletConnection.js";
+import { transactionRequestSchema } from "./transactionRequest.js";
+import { workflowProgress } from "./walletConnection.js";
+import { reviewProgress, EXECUTION_POLLING_INTERVAL_SECONDS } from "./status.js";
+import { walletRunIdSchema, walletRecoverySchema, walletObservationSchema } from "./walletRuntime.js";
+export const CONNECT_BOUNDARY = "A wallet connection provides account context; it is not a transaction approval or proof of address ownership.";
+export const REVIEW_BOUNDARY = "Review evidence is not a safety guarantee. Only an explicit card action and wallet approval may authorize this exact transaction.";
+// A projection of an admitted card operation, not a new wallet connection state.
+export const connectionViewSchema = walletConnectionSchema.extend({ pendingAction: z.literal("disconnect").optional() });
+export { assetReadAccountSchema } from "./walletConnection.js";
+export const pendingConnectionStatusSchema = z.enum(["input_required", "awaiting_approval", "disconnect_pending"]);
+const connectAction = z.object({ action: z.literal("connect"), walletRunId: walletRunIdSchema }).strict();
+const disconnectAction = z.object({ action: z.literal("disconnect"), walletRunId: walletRunIdSchema, connectionId: z.string().min(1) }).strict();
+const accountAction = z.object({ action: z.literal("use_account"), walletRunId: walletRunIdSchema, connectionId: z.string().min(1), account: suiAddressStringSchema }).strict();
+const reviewAction = z.object({ action: z.enum(["prepare_review", "request_signature"]), connectionId: z.string().min(1),
+    walletRunId: walletRunIdSchema, account: suiAddressStringSchema, reviewRevision: z.number().int().nonnegative() }).strict();
+const simpleAction = z.object({ action: z.enum(["cancel", "stop_connection", "stop_waiting", "read_result"]) }).strict();
+export const workflowActionSchema = z.union([connectAction, disconnectAction, accountAction, reviewAction, simpleAction]);
+export const automaticWorkflowActionSchema = z.union([connectAction, reviewAction.extend({ action: z.literal("prepare_review") })]);
+export function parseWorkflowAction(input) {
+    const action = workflowActionSchema.parse(input);
+    return "account" in action ? { ...action, account: parseSuiAddress(action.account) } : action;
+}
+export const workflowViewSchema = z.object({
+    kind: z.enum(["connect", "review"]),
+    mode: z.enum(["connect", "review", "review_manage"]),
+    allowedActions: z.array(z.enum(workflowActions)),
+    actionRemainingMs: z.number().int().nonnegative(),
+    nextStateReadAfterMs: z.number().int().nonnegative().optional(),
+    automaticAction: automaticWorkflowActionSchema.optional(),
+    observe: z.boolean(),
+    walletAvailability: walletAvailabilitySchema,
+    walletObservation: walletObservationSchema.optional(),
+    runtimeRecovery: walletRecoverySchema.optional(),
+    connectionConflict: connectionConflictSchema.optional(),
+    usableConnectionId: z.string().min(1).optional(),
+    assetReadAccount: assetReadAccountSchema.optional(),
+    acceptedWalletRunId: walletRunIdSchema.optional(),
+    progress: workflowProgressSchema,
+    boundary: z.enum([CONNECT_BOUNDARY, REVIEW_BOUNDARY]),
+    connections: z.array(connectionViewSchema),
+    activeAccount: z.string().optional(),
+    connection: connectionViewSchema.optional(),
+    connectionAction: z.enum(["connect", "disconnect"]).optional(),
+    review: z.object({
+        reviewSessionId: z.string(), plan: actionPlanSchema, reviewRevision: z.number().int().nonnegative(),
+        status: internalSessionStatusSchema, account: z.string().optional(), preparing: z.boolean(),
+        accountRequestPending: z.literal(true).optional(),
+        error: z.string().optional(),
+        state: reviewStateOutputSchema.optional()
+    }).strict().optional(),
+    request: transactionRequestSchema.optional(),
+    receipt: z.unknown().optional(),
+    netGasMist: z.string().regex(/^-?[0-9]+$/).optional(),
+    observationStopped: z.boolean().optional()
+}).strict().superRefine((view, context) => {
+    const connection = view.connections.find((item) => item.connectionId === view.usableConnectionId);
+    if (view.usableConnectionId && (!connection || connection.status !== "connected" ||
+        view.walletAvailability.status !== "available" || view.connectionConflict ||
+        view.connections.some((item) => item.pendingAction || item.status === "awaiting_approval"))) {
+        context.addIssue({ code: "custom", path: ["usableConnectionId"], message: "The usable connection must match current connection facts." });
+    }
+    if (view.assetReadAccount?.status === "available" && (!connection ||
+        !connection.accounts.includes(view.assetReadAccount.account) || view.activeAccount !== view.assetReadAccount.account)) {
+        context.addIssue({ code: "custom", path: ["assetReadAccount"], message: "The default address must belong to the usable connection and stored selection." });
+    }
+});
+// Automatic preparation uses the same current selection and typed admission as
+// a deliberate retry. A failed computation is not a reason to compute in a loop.
+function automaticReviewAction(input) {
+    const { record, session, request } = input;
+    if (!session || record?.scope !== "review" || request || session.preparationError ||
+        !input.allowedActions.includes("prepare_review"))
+        return undefined;
+    const needsPreparation = !session.reviewState && session.reviewRevision === 0 ||
+        session.reviewState?.status === "refresh_required" && session.reviewState.refreshReason === "review_evidence_stale";
+    if (!needsPreparation || input.assetReadAccount?.status !== "available")
+        return undefined;
+    const account = input.assetReadAccount.account;
+    const candidates = reviewWalletChoices(input, account);
+    if (candidates.length !== 1)
+        return undefined;
+    return { action: "prepare_review", walletRunId: input.walletAvailability.walletRunId, connectionId: candidates[0].connectionId,
+        account, reviewRevision: session.reviewRevision };
+}
+// Method support filters wallet choices; it does not authorize a signature.
+export function reviewWalletChoices(selection, account, requireSigningMethod = false) {
+    return selection.connections.filter((item) => item.connectionId === selection.usableConnectionId && item.accounts.includes(account) &&
+        (!requireSigningMethod || item.methods.includes("sui_signTransaction")));
+}
+function nextStateRead(input) {
+    const walletInput = input.record?.state.state === "ready" && input.record.scope !== "review_manage" && !input.request &&
+        !input.session?.plans[0]?.reviewModel && input.inputRemainingMs > 0;
+    const startup = walletInput && ["initializing", "recovering"].includes(input.walletAvailability.status);
+    const delays = [input.nextStateReadAfterMs, startup ? WALLET_CONNECTION_POLL_SECONDS * 1000 : undefined,
+        walletInput && input.record?.scope === "review" && input.busyForAccount ? EXECUTION_POLLING_INTERVAL_SECONDS * 1000 : undefined]
+        .filter((value) => value !== undefined && value > 0);
+    return delays.length ? Math.min(...delays) : undefined;
+}
+// These projections do not read clocks, storage, or admission rules. The
+// evaluated facts and choices were collected together by the database owner.
+export function projectConnectionView(input) {
+    const { connection, walletAvailability } = input;
+    const readAfter = nextStateRead(input);
+    const progress = input.runtimeRecovery ? { status: "phase" in input.runtimeRecovery ? "waiting" : "idle" } :
+        workflowProgress(connection?.status === "awaiting_approval" || connection?.pendingAction === "disconnect", true, walletAvailability);
+    return workflowViewSchema.parse({ kind: "connect", mode: "connect", allowedActions: input.allowedActions,
+        actionRemainingMs: input.actionRemainingMs, observe: progress.status === "waiting", progress, walletAvailability,
+        ...(input.record?.state.input.intent === "connect" && input.allowedActions.includes("connect")
+            ? { automaticAction: { action: "connect", walletRunId: walletAvailability.walletRunId } } : {}),
+        runtimeRecovery: input.runtimeRecovery, walletObservation: input.walletObservation,
+        connectionConflict: input.connectionConflict, usableConnectionId: input.usableConnectionId, assetReadAccount: input.assetReadAccount,
+        connectionAction: ["connect", "disconnect"].includes(String(input.record?.acceptedInput?.action)) ? input.record?.acceptedInput?.action : undefined,
+        acceptedWalletRunId: input.record?.acceptedInput?.walletRunId,
+        ...(readAfter === undefined ? {} : { nextStateReadAfterMs: readAfter }),
+        connections: input.connections, activeAccount: input.activeAccount, connection, boundary: CONNECT_BOUNDARY });
+}
+export function projectReviewView(input) {
+    const { record, session, request, authority, walletAvailability, boundReview } = input;
+    if (!record || !session)
+        throw new Error("Review projection requires an evaluated card and session.");
+    const progress = reviewProgress(!boundReview && !!session.preparationId, request, walletAvailability, {
+        stopped: authority?.observation_stopped === 1, pending: authority?.lookup_pending === 1
+    });
+    const displayedReview = boundReview ?? session.reviewState;
+    const gas = displayedReview?.simulation?.gasCostSummary;
+    const automaticAction = automaticReviewAction(input);
+    const readAfter = nextStateRead(input);
+    return workflowViewSchema.parse({ kind: "review", mode: record.scope === "review_manage" ? "review_manage" : "review",
+        allowedActions: input.allowedActions, actionRemainingMs: input.actionRemainingMs, observe: progress.status === "waiting", progress, walletAvailability,
+        connections: input.connections, connectionConflict: input.connectionConflict, usableConnectionId: input.usableConnectionId,
+        assetReadAccount: input.assetReadAccount, activeAccount: input.activeAccount, boundary: REVIEW_BOUNDARY, receipt: input.receipt,
+        walletObservation: input.walletObservation,
+        acceptedWalletRunId: record.acceptedInput?.walletRunId,
+        ...(readAfter === undefined ? {} : { nextStateReadAfterMs: readAfter }),
+        ...(automaticAction ? { automaticAction } : {}),
+        netGasMist: gas ? (BigInt(gas.computationCostRaw) + BigInt(gas.storageCostRaw) - BigInt(gas.storageRebateRaw)).toString() : undefined,
+        review: { reviewSessionId: session.id, plan: session.plans[0], reviewRevision: boundReview && request ? request.reviewRevision : session.reviewRevision,
+            status: boundReview?.status ?? session.status, account: boundReview?.account ?? session.account,
+            ...(!request && !session.plans[0]?.reviewModel && input.busyForAccount ? { accountRequestPending: true } : {}),
+            preparing: !boundReview && !!session.preparationId,
+            error: !boundReview ? [input.preparationIssue && `Current account selection: ${input.preparationIssue}`,
+                session.preparationError && `Earlier review message: “${session.preparationError}”`].filter(Boolean).join("\n\n") || undefined : undefined,
+            state: displayedReview },
+        request, observationStopped: authority ? authority.observation_stopped === 1 : undefined });
+}

package/dist/core/suiAddress.js

@@ -0,0 +1,18 @@
+import { isValidSuiAddress, isValidTransactionDigest, normalizeSuiAddress } from "@mysten/sui/utils";
+import { z } from "zod";
+// Use the string-only schema at MCP/HTTP output boundaries because zod transforms
+// cannot be represented in MCP JSON Schema. Use the normalized schema for values
+// before storing them as local session state.
+export const suiAddressStringSchema = z
+    .string()
+    .refine(isValidSuiAddress, "Expected a 32-byte Sui address");
+// Shared Sui transaction digest schema (pinned SDK source of truth). Used at
+// MCP/HTTP boundaries and by the signable-adapter commitment fields.
+export const suiTransactionDigestSchema = z
+    .string()
+    .refine(isValidTransactionDigest, "Expected a Sui transaction digest");
+export const normalizedSuiAddressSchema = suiAddressStringSchema.transform((value) => normalizeSuiAddress(value));
+export function parseSuiAddress(value) {
+    const parsed = normalizedSuiAddressSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}

package/dist/core/suiEndpoint.js

@@ -0,0 +1,72 @@
+export class SuiEndpointError extends Error {
+    kind;
+    details;
+    constructor(kind, message, details = {}) {
+        super(message);
+        this.kind = kind;
+        this.details = details;
+    }
+}
+export const MAX_SUI_GRPC_URL_LENGTH = 512;
+export const MAX_SUI_GRAPHQL_URL_LENGTH = 512;
+export function parseGrpcUrl(value) {
+    let parsed;
+    if (value.length > MAX_SUI_GRPC_URL_LENGTH) {
+        throw new SuiEndpointError("invalid_url", `Sui gRPC URL must be ${MAX_SUI_GRPC_URL_LENGTH} characters or fewer`);
+    }
+    const authority = getUrlAuthority(value);
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new SuiEndpointError("invalid_url", "Sui gRPC URL must be a valid http(s) URL with an explicit port");
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new SuiEndpointError("invalid_url", "Sui gRPC URL must use http or https");
+    }
+    if (!authority || !hasExplicitPort(authority)) {
+        throw new SuiEndpointError("invalid_url", "Sui gRPC URL must include an explicit port, for example :443 or :9000");
+    }
+    if (authority.includes("@")) {
+        throw new SuiEndpointError("invalid_url", "Sui gRPC URL must not include credentials");
+    }
+    if (parsed.pathname !== "/" || parsed.search || parsed.hash) {
+        throw new SuiEndpointError("invalid_url", "Sui gRPC URL must include only scheme, host, and explicit port");
+    }
+    return `${parsed.protocol}//${authority}`;
+}
+// GraphQL endpoints commonly include a path such as /graphql and may omit an
+// explicit port. gRPC endpoints stay stricter because the pinned gRPC client
+// runtime expects only scheme, host, and explicit port.
+export function parseGraphqlUrl(value) {
+    let parsed;
+    if (value.length > MAX_SUI_GRAPHQL_URL_LENGTH) {
+        throw new SuiEndpointError("invalid_url", `Sui GraphQL URL must be ${MAX_SUI_GRAPHQL_URL_LENGTH} characters or fewer`);
+    }
+    const authority = getUrlAuthority(value);
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new SuiEndpointError("invalid_url", "Sui GraphQL URL must be a valid https URL");
+    }
+    if (parsed.protocol !== "https:") {
+        throw new SuiEndpointError("invalid_url", "Sui GraphQL URL must use https");
+    }
+    if (!authority) {
+        throw new SuiEndpointError("invalid_url", "Sui GraphQL URL must include a host");
+    }
+    if (authority.includes("@")) {
+        throw new SuiEndpointError("invalid_url", "Sui GraphQL URL must not include credentials");
+    }
+    if (parsed.search || parsed.hash) {
+        throw new SuiEndpointError("invalid_url", "Sui GraphQL URL must not include a query string or fragment");
+    }
+    return parsed.toString();
+}
+function getUrlAuthority(value) {
+    return value.match(/^[a-z][a-z0-9+.-]*:\/\/([^/?#]+)/i)?.[1];
+}
+function hasExplicitPort(authority) {
+    return /\]:\d+$/.test(authority) || /^[^[]*:\d+$/.test(authority);
+}

package/dist/mcp/activeAccountResponse.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export const activeAccountResponseSchema = z.discriminatedUnion("status", [
+    z.object({
+        status: z.literal("set"),
+        account: z.string(),
+        source: z.literal("wallet_connection"),
+        setAt: z.string(),
+        boundary: z.literal("read_context_only_not_signing_authorization")
+    }),
+    z.object({
+        status: z.literal("none")
+    })
+]);
+export function activeAccountResponse(active) {
+    return active
+        ? {
+            status: "set",
+            account: active.address,
+            source: active.source,
+            setAt: active.setAt,
+            boundary: "read_context_only_not_signing_authorization"
+        }
+        : { status: "none" };
+}

package/dist/mcp/prompts.js

@@ -0,0 +1,146 @@
+import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
+import { z } from "zod";
+import { actionGroups, promptNameFor } from "../adapters/adapterPromptSurfaces.js";
+export const MCP_PROMPTS = [
+    {
+        name: "inspect-supported-sui-actions",
+        title: "Inspect Supported Sui Actions",
+        description: "Review current supported mainnet surfaces and tool status.",
+        text: [
+            "Inspect the Sui MCP server status and supported mainnet Sui protocol surfaces.",
+            "Use read.get_server_status first, then read.list_supported_protocols.",
+            "Report implemented tools separately from unavailable or blocked surfaces."
+        ].join("\n")
+    },
+    {
+        name: "prepare-reviewable-sui-action",
+        title: "Prepare Reviewable Sui Action",
+        description: "Prepare a local review session for a supported action proposal.",
+        text: [
+            "Prepare a reviewable Sui action only through Sui MCP's review-session flow.",
+            "Use action.prepare_external_proposal_review when the input is a structured external payment or Sui action proposal.",
+            "External proposals get read-only local review and never become signing material. Use action.prepare_sui_action_review for a natural-language swap intent; after a wallet account is connected, account-bound review can reach ready_for_wallet_review, where an explicit Review card action can request approval in the user’s wallet through the backend.",
+            "Present the internal Review card and summarize the returned review checks. This MCP response never contains signing data, transaction bytes, or signing readiness; only an explicit UI action and wallet approval authorize the backend request; request status is separate from server-verified chain execution facts."
+        ].join("\n")
+    }
+];
+// Platform-owned boundary language appended to every adapter prompt surface.
+// Adapters contribute copy about their own action only; they cannot weaken
+// or omit these lines.
+const PLATFORM_PROMPT_BOUNDARY_LINES = [
+    "Present the internal Review card and summarize the returned review checks.",
+    "This MCP response never contains signing data, transaction bytes, or signing readiness; only an explicit UI action and wallet approval authorize the backend request; request status is separate from server-verified chain execution facts."
+];
+function surfacePromptText(surface, intent) {
+    return [
+        `Prepare a reviewable Sui mainnet ${surface.action} for this intent: "${intent}".`,
+        `Parse the source amount, source symbol, and target symbol from the intent (any language) and call ${surface.toolName} with them and intent.protocol set to "${surface.protocolSlug}".`,
+        ...PLATFORM_PROMPT_BOUNDARY_LINES
+    ].join("\n");
+}
+function registerSurfacePrompt(server, name, surface, description) {
+    server.registerPrompt(name, {
+        title: surface.title,
+        description,
+        argsSchema: {
+            intent: z.string().describe(surface.intentArgDescription)
+        }
+    }, async ({ intent }) => ({
+        description,
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: surfacePromptText(surface, intent)
+                }
+            }
+        ]
+    }));
+}
+export function registerMcpPrompts(server, surfaces = []) {
+    for (const prompt of MCP_PROMPTS) {
+        server.registerPrompt(prompt.name, {
+            title: prompt.title,
+            description: prompt.description
+        }, async () => ({
+            description: prompt.description,
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: prompt.text
+                    }
+                }
+            ]
+        }));
+    }
+    // Adapter prompt surfaces: action-first names (`swap-deep`) with one
+    // free-text intent argument so clients can pass the whole request in one
+    // line (Claude Code: /mcp__sui-mcp__swap-deep 10 sui to usdc;
+    // Claude Desktop shows a single input field). The model parses the
+    // intent; this server never does.
+    for (const surface of surfaces) {
+        registerSurfacePrompt(server, promptNameFor(surface), surface, surface.description);
+    }
+    // Bare action prompts are always registered. One protocol: straight to it.
+    // Several protocols: an optional `protocol` argument (completion suggests
+    // the slugs) and explicit instructions to ask the user - the venue is the
+    // user's choice, never the server's.
+    for (const [action, group] of actionGroups(surfaces)) {
+        registerBareActionPrompt(server, action, group);
+    }
+}
+export function bareActionPromptText(action, group, intent, protocol) {
+    const chosen = group.length === 1 ? group[0] : group.find((surface) => surface.protocolSlug === (protocol ?? "").trim());
+    if (chosen) {
+        return surfacePromptText(chosen, intent);
+    }
+    const options = group
+        .map((surface) => `${surface.protocolSlug} (${surface.title}, tool: ${surface.toolName})`)
+        .join("; ");
+    return [
+        `Several protocols support the ${action} action: ${options}.`,
+        `The user's intent: "${intent}".`,
+        "List these protocol options to the user and ask which one to use. Do not pick a protocol on your own.",
+        "Once the user names a protocol, parse the source amount, source symbol, and target symbol from the intent (any language) and call that protocol's tool with them and intent.protocol set to the chosen slug.",
+        ...PLATFORM_PROMPT_BOUNDARY_LINES
+    ].join("\n");
+}
+function registerBareActionPrompt(server, action, group) {
+    const single = group.length === 1 ? group[0] : undefined;
+    const first = group[0];
+    if (!first) {
+        return;
+    }
+    const description = single
+        ? `${single.description} Shorthand for ${promptNameFor(single)}.`
+        : `Prepare a reviewable Sui ${action} - several protocols support it (${group
+            .map((surface) => surface.protocolSlug)
+            .join(", ")}); you pick which.`;
+    const slugs = group.map((surface) => surface.protocolSlug);
+    server.registerPrompt(action, {
+        title: single ? single.title : `${action} (choose protocol)`,
+        description,
+        argsSchema: {
+            intent: completable(z.string().describe(first.intentArgDescription), (value) => value ? [] : group.flatMap((surface) => surface.exampleIntents)),
+            ...(single
+                ? {}
+                : {
+                    protocol: completable(z.string().optional().describe(`Protocol slug (optional): ${slugs.join(" | ")}`), (value) => slugs.filter((slug) => slug.startsWith((value ?? "").toLowerCase())))
+                })
+        }
+    }, async (args) => ({
+        description,
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: bareActionPromptText(action, group, String(args.intent ?? ""), args.protocol)
+                }
+            }
+        ]
+    }));
+}

package/dist/mcp/registerTool.js

@@ -0,0 +1,19 @@
+import { assertValidToolName } from "./toolNames.js";
+const DEFAULT_TOOL_ANNOTATIONS = {
+    openWorldHint: false
+};
+function mergedAnnotations(defaultAnnotations, annotations) {
+    return {
+        ...DEFAULT_TOOL_ANNOTATIONS,
+        ...(defaultAnnotations ?? {}),
+        ...(annotations ?? {})
+    };
+}
+export function registerSuiMcpTool(server, name, config, callback) {
+    assertValidToolName(name);
+    const { defaultAnnotations, annotations, ...sdkConfig } = config;
+    return server.registerTool(name, {
+        ...sdkConfig,
+        annotations: mergedAnnotations(defaultAnnotations, annotations)
+    }, callback);
+}

package/dist/mcp/resources.js

@@ -0,0 +1,72 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+export const MCP_RESOURCES = [
+    {
+        name: "readme",
+        uri: "suimcp://docs/readme",
+        title: "README",
+        description: "Public entry document: product purpose, current release boundary, setup path, and documentation map.",
+        path: "README.md"
+    },
+    {
+        name: "mcp-setup",
+        uri: "suimcp://docs/mcp-setup",
+        title: "MCP Setup",
+        description: "Setup guide: installation, MCP client connection, first-use flow, settings, and troubleshooting.",
+        path: "docs/MCP_SETUP.md"
+    },
+    {
+        name: "mcp-tools",
+        uri: "suimcp://docs/mcp-tools",
+        title: "MCP Tools",
+        description: "API reference: tool contracts, response fields, statuses, follow-up fields, and output boundaries.",
+        path: "docs/MCP_TOOLS.md"
+    },
+    {
+        name: "wallet-connection",
+        uri: "suimcp://docs/wallet-connection",
+        title: "Wallet Connection",
+        description: "Wallet connection reference: active read context, private SDK ownership and user-approved transaction requests.",
+        path: "docs/WALLET_CONNECTION.md"
+    },
+    {
+        name: "agent-behavior",
+        uri: "suimcp://docs/agent-behavior",
+        title: "Agent Behavior Reference",
+        description: "Answer playbook: user-question flows, tool selection, and response wording boundaries.",
+        path: "docs/AGENT_BEHAVIOR.md"
+    },
+    {
+        name: "deepbook-v3",
+        uri: "suimcp://protocols/deepbook-v3",
+        title: "DeepBookV3",
+        description: "Protocol reference only; use MCP tool responses and read.list_supported_protocols for current support.",
+        path: "protocols/deepbook-v3.md"
+    },
+    {
+        name: "deepbook-margin",
+        uri: "suimcp://protocols/deepbook-margin",
+        title: "DeepBook Margin",
+        description: "Protocol reference only; no margin MCP read tools or signable actions are exposed in this release.",
+        path: "protocols/deepbook-margin.md"
+    }
+];
+export function registerMcpResources(server) {
+    for (const resource of MCP_RESOURCES) {
+        server.registerResource(resource.name, resource.uri, {
+            title: resource.title,
+            description: resource.description,
+            mimeType: "text/markdown"
+        }, async () => ({
+            contents: [
+                {
+                    uri: resource.uri,
+                    mimeType: "text/markdown",
+                    text: await readFile(resolve(packageRoot, resource.path), "utf8")
+                }
+            ]
+        }));
+    }
+}